Metadata-Version: 2.4
Name: datarails-finance-os-mcp
Version: 2.0.2
Summary: MCP server for Datarails Finance OS integration with Claude
Project-URL: Homepage, https://github.com/Datarails/dr-datarails-mcp-re
Project-URL: Documentation, https://github.com/Datarails/dr-datarails-mcp-re#readme
Project-URL: Repository, https://github.com/Datarails/dr-datarails-mcp-re
Project-URL: Issues, https://github.com/Datarails/dr-datarails-mcp-re/issues
Author: Datarails
License-Expression: MIT
Keywords: ai,anthropic,claude,datarails,finance,mcp
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Requires-Python: >=3.10
Requires-Dist: aiohttp>=3.9.0
Requires-Dist: click>=8.0.0
Requires-Dist: httpx>=0.27.0
Requires-Dist: keyring>=25.0.0
Requires-Dist: mcp>=1.0.0
Requires-Dist: pydantic>=2.0.0
Provides-Extra: all
Requires-Dist: matplotlib>=3.8.0; extra == 'all'
Requires-Dist: openpyxl>=3.1.5; extra == 'all'
Requires-Dist: pandas>=2.1.0; extra == 'all'
Requires-Dist: pillow>=12.1.1; extra == 'all'
Requires-Dist: python-pptx>=0.6.23; extra == 'all'
Requires-Dist: reportlab>=4.0.0; extra == 'all'
Requires-Dist: rich>=13.0.0; extra == 'all'
Provides-Extra: dev
Requires-Dist: pytest-asyncio>=0.23.0; extra == 'dev'
Requires-Dist: pytest>=8.0.0; extra == 'dev'
Requires-Dist: respx>=0.21.0; extra == 'dev'
Requires-Dist: rich>=13.0.0; extra == 'dev'
Provides-Extra: reports
Requires-Dist: matplotlib>=3.8.0; extra == 'reports'
Requires-Dist: openpyxl>=3.1.5; extra == 'reports'
Requires-Dist: pandas>=2.1.0; extra == 'reports'
Requires-Dist: pillow>=12.1.1; extra == 'reports'
Requires-Dist: python-pptx>=0.6.23; extra == 'reports'
Requires-Dist: reportlab>=4.0.0; extra == 'reports'
Provides-Extra: rich
Requires-Dist: rich>=13.0.0; extra == 'rich'
Description-Content-Type: text/markdown

# Datarails Finance OS MCP Server

A [Model Context Protocol](https://modelcontextprotocol.io) (MCP) server that connects Claude to [Datarails](https://datarails.com) Finance OS for financial data analysis, profiling, and reporting.

## Prerequisites

- **Python 3.10+** — [python.org/downloads](https://www.python.org/downloads/)
- **Claude Code** — `npm install -g @anthropic-ai/claude-code` (requires [Node.js 18+](https://nodejs.org/))

## Setup

### Step 1: Install

```bash
pip install datarails-finance-os-mcp
```

With report generation (Excel, PowerPoint, PDF):
```bash
pip install datarails-finance-os-mcp[reports]
```

### Step 2: Authenticate

```bash
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

```bash
datarails-mcp setup --claude-code
```

Or manually:
```bash
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

```bash
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`):
```json
{
  "mcpServers": {
    "datarails-finance-os": {
      "command": "datarails-mcp",
      "args": ["serve"]
    }
  }
}
```

**Project-level** (`.mcp.json`):
```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

```bash
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:

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

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

## Development

```bash
# 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](https://github.com/Datarails/dr-claude-code-plugins-re) - Claude Code + Cowork plugin with 16 financial analysis skills

## License

MIT