Datarails Finance OS MCP Server

A Model Context Protocol (MCP) server that connects Claude to Datarails Finance OS for financial data analysis, profiling, and reporting.

Prerequisites

• Python 3.10+ — python.org/downloads
• Claude Code — npm install -g @anthropic-ai/claude-code (requires Node.js 18+)

Setup

Step 1: Install

pip install datarails-finance-os-mcp

With report generation (Excel, PowerPoint, PDF):

pip install datarails-finance-os-mcp[reports]

Step 2: Authenticate

datarails-mcp authenticate

This opens your browser where you log in, select your environment, and grant consent. Tokens are stored securely in your system keychain. JWT tokens auto-refresh when expired.

Step 3: Connect to Claude Code

datarails-mcp setup --claude-code

Or manually:

claude mcp add datarails-finance-os -- datarails-mcp serve

Step 4: Restart Claude Code

Close and reopen Claude Code for the MCP server to appear.

Verify

datarails-mcp status

Should show:

✓ Authenticated
• Organization: yourcompany.com
• Environment: https://app.datarails.com
• API URL: https://app.datarails.com/finance-os/api

Claude Desktop (add to claude_desktop_config.json):

{
  "mcpServers": {
    "datarails-finance-os": {
      "command": "datarails-mcp",
      "args": ["serve"]
    }
  }
}

Project-level (.mcp.json):

{
  "mcpServers": {
    "datarails-finance-os": {
      "command": "uvx",
      "args": ["datarails-finance-os-mcp", "serve"]
    }
  }
}

Available MCP Tools

Authentication

Tool	Description
authenticate	Connect to Datarails via OAuth (opens browser)
disable	Disconnect — revoke tokens and clear credentials
auth_status	Check current authentication status

Discovery & Profiling

Tool	Description
list_finance_tables	Discover available tables
get_table_schema	Get column names, types, relationships
get_field_distinct_values	Unique values for a field
profile_table_summary	Row counts, data quality score
profile_numeric_fields	Min/max/avg/outliers for numeric fields
profile_categorical_fields	Cardinality, frequencies for categorical fields
detect_anomalies	Auto-detect data quality issues

Querying & Aggregation

Tool	Description
get_records_by_filter	Fetch filtered records (max 500 rows)
get_sample_records	Random sample for quick inspection
execute_query	Custom SQL-like queries (max 1000 rows)
aggregate_table_data	Grouped aggregations with no row limit

Reports & Workflows

Tool	Description
get_workflow_guide	Guided workflows for common analysis tasks
generate_intelligence_workbook	FP&A intelligence workbook (Excel)
extract_financials	Extract validated financial data to Excel

CLI Commands

datarails-mcp authenticate              # Connect via OAuth (opens browser)
datarails-mcp authenticate --env dev    # Use dev auth server
datarails-mcp authenticate --env test   # Use test auth server
datarails-mcp disable                   # Disconnect and clear tokens
datarails-mcp status                    # Check auth status
datarails-mcp status --json             # JSON output
datarails-mcp serve                     # Start the MCP server (used by Claude)
datarails-mcp setup                     # Auto-configure Claude clients

Configuration

Client Profiles

Client profiles store table IDs, field mappings, and aggregation hints:

config/client-profiles/production.json
config/client-profiles/development.json

These are generated by the plugin's /dr-learn skill and are not committed to git.

Report Scripts

The scripts/ directory contains Python scripts for generating financial reports. These require the reports extra:

pip install datarails-finance-os-mcp[reports]

Reports use the authenticated session — run datarails-mcp authenticate first.

Development

# Clone and install for development
git clone https://github.com/Datarails/dr-datarails-mcp-re.git
cd dr-datarails-mcp-re
pip install -e ".[dev,reports]"

# Run tests
pytest

# Run server locally
datarails-mcp serve

Architecture

datarails-mcp/
├── src/datarails_mcp/     # MCP server source
│   ├── server.py          # MCP tool definitions
│   ├── client.py          # Datarails API client (JWT auto-refresh)
│   ├── oauth.py           # OAuth 2.0 + PKCE authentication flow
│   ├── token_store.py     # Keyring-backed credential storage
│   ├── cli.py             # CLI commands (authenticate, disable, status, serve, setup)
│   ├── constants.py       # Auth server config, timeouts
│   ├── excel_builder.py   # Excel report generation
│   ├── pptx_builder.py    # PowerPoint generation
│   ├── pdf_builder.py     # PDF generation
│   ├── chart_builder.py   # Chart generation
│   └── report_utils.py    # Shared report utilities
├── scripts/               # Standalone report scripts
├── templates/             # Report templates
└── tests/                 # Test suite

Used By

• Datarails Finance OS Plugin - Claude Code + Cowork plugin with 16 financial analysis skills

License

MIT