finstatement-mcp 0.1.0

MCP server for FinStatement Pro — read-only financial statement queries via Claude, ChatGPT, Cursor, and other MCP clients.

FinStatement Pro — MCP Server

Read-only Model Context Protocol server that exposes FinStatement Pro to Claude Desktop, ChatGPT Desktop, Cursor, Cline, and any other MCP client. 20 tools — 19 read + 1 workspace switcher for users who hold both editions (Single Entity ↔ Holding) under the same email.

Once installed, your client's LLM can answer questions like:

• "Pull the consolidated balance sheet for run 12 and flag any line item that moved >10% YoY"
• "Why does goodwill on the consolidated BS differ from what's on the parent's standalone? Show me the eliminations."
• "Summarise our FCTR movements this period — which subsidiary contributed most?"
• "List all intercompany transactions over ₹50 lakh in FY24-25."
• "Show me the trial balance for ABC Ltd Q3 and identify accounts with material variances vs Q2."

Status

v0.1 — read-only prototype. No mutating tools yet. Designed to validate whether MCP is genuinely useful for finance teams before investing in the mutating tool surface (post-journal, run-consolidation, etc.).

Tools exposed

Category	Tool
Identity	whoami
Companies	list_companies, get_company
Periods	list_periods
Trial balance	list_trial_balances, get_trial_balance_line_items
Single-entity statements	get_balance_sheet, get_profit_and_loss, get_cash_flow
Consolidation structure	list_groups, get_group_tree
Consolidation runs	list_consolidation_runs
Consolidated statements	get_consolidated_balance_sheet, get_consolidated_profit_and_loss, get_consolidated_cash_flow
Consolidation artifacts	get_eliminations, get_nci, get_fctr
Intercompany	list_intercompany_transactions
Workspace	switch_workspace (multi-membership users only)

Install

Requires Python 3.10+.

Recommended — pipx (isolated, one command)

pipx install finstatement-mcp

pipx puts the MCP server in its own venv (no clash with your system Python or other tools) and exposes the finstatement-mcp command on your PATH. To upgrade later: pipx upgrade finstatement-mcp. To remove: pipx uninstall finstatement-mcp.

If you don't have pipx yet: python -m pip install --user pipx && python -m pipx ensurepath.

Alternative — uv (also isolated, faster)

uv tool install finstatement-mcp

From source (for contributors)

Always install in an isolated venv — the MCP SDK pulls newer starlette and pydantic than the backend uses, so a global install will break the FastAPI backend in the same Python env.

cd 6_mcp
python -m venv .venv

# Windows
.venv\Scripts\pip install -e .

# macOS/Linux
.venv/bin/pip install -e .

To verify it imported cleanly:

# Windows
.venv\Scripts\python -c "from finstatement_mcp import server; print('ok')"

# macOS/Linux
.venv/bin/python -c "from finstatement_mcp import server; print('ok')"

Configure

Either copy .env.example to .env and edit, or pass env vars in the Claude Desktop config (see below).

Recommended — API key (issue from the in-app dashboard, doesn't expire, revocable per-key, survives password rotations):

FINSTATEMENT_BASE_URL=http://localhost:8000
FINSTATEMENT_API_KEY=fs_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx

Alternatively — email + password (lazy login, JWT cached in memory, 8h TTL):

FINSTATEMENT_BASE_URL=http://localhost:8000
FINSTATEMENT_EMAIL=[e-mail]
FINSTATEMENT_PASSWORD=your-password

Auth precedence (first match wins): FINSTATEMENT_API_KEY → FINSTATEMENT_JWT → email + password.

Wire into Claude Desktop

Edit claude_desktop_config.json:

• macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
• Windows: %APPDATA%\Claude\claude_desktop_config.json

Add an entry under mcpServers. Three patterns — pick one:

Pattern A — pipx (recommended once published)

Cleanest install. After pipx install finstatement-mcp, the finstatement-mcp command is on your PATH and works from any directory:

{
  "mcpServers": {
    "finstatement-pro": {
      "command": "finstatement-mcp",
      "env": {
        "FINSTATEMENT_BASE_URL": "https://brd-software-production.up.railway.app",
        "FINSTATEMENT_API_KEY": "fs_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"
      }
    }
  }
}

If finstatement-mcp isn't found by Claude Desktop, replace "command": "finstatement-mcp" with the absolute path that pipx list shows for the binary (e.g. C:/Users/you/.local/bin/finstatement-mcp.exe).

Pattern B — venv from source (works everywhere, requires repo clone)

Point command at the venv's Python directly. This guarantees the right deps are loaded regardless of what's in your global env or PATH.

{
  "mcpServers": {
    "finstatement-pro": {
      "command": "C:/Users/suhit/OneDrive/Desktop/FinStatements_App/6_mcp/.venv/Scripts/python.exe",
      "args": ["-m", "finstatement_mcp"],
      "env": {
        "FINSTATEMENT_BASE_URL": "http://localhost:8000",
        "FINSTATEMENT_API_KEY": "fs_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"
      }
    }
  }
}

(macOS/Linux: replace the command path with .venv/bin/python.) (Email/password also works — swap the FINSTATEMENT_API_KEY line for FINSTATEMENT_EMAIL and FINSTATEMENT_PASSWORD.)

Pattern C — uvx (alternative for uv users)

uv handles env isolation transparently:

{
  "mcpServers": {
    "finstatement-pro": {
      "command": "uvx",
      "args": [
        "--from",
        "C:/Users/suhit/OneDrive/Desktop/FinStatements_App/6_mcp",
        "finstatement-mcp"
      ],
      "env": {
        "FINSTATEMENT_BASE_URL": "http://localhost:8000",
        "FINSTATEMENT_API_KEY": "fs_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"
      }
    }
  }
}

After saving, fully quit and relaunch Claude Desktop. You should see finstatement-pro listed under the tools/connectors icon in the chat input.

Smoke test prompts

In a fresh Claude Desktop chat, try these in order:

1. "Use the finstatement-pro server. Call whoami and tell me who I'm logged in as."
2. "List all my companies."
3. "List the periods for company id 1."
4. "Get the balance sheet for company 1 period 1 and summarise it in 5 lines."
5. "List my consolidation groups."
6. "For consolidation run 1, show me the FCTR movements and explain which subsidiary drove the largest movement."

If step 1 fails: the server can't reach the backend or auth isn't working. Check that the backend is running, env vars are set, and credentials are valid.

If steps 2+ work but feel slow: that's free-tier Railway cold-start latency, not the MCP layer. Run the backend locally for snappy responses.

How auth works

The server reads FINSTATEMENT_JWT first; if absent, it logs in once with FINSTATEMENT_EMAIL + FINSTATEMENT_PASSWORD and caches the JWT in memory. On HTTP 401 it transparently re-logs in if email/password were provided.

JWTs expire after 8 hours. For long Claude Desktop sessions, prefer the email/password mode so the server can refresh on its own.

Troubleshooting

"Server failed to start"

• Check that finstatement-mcp is on PATH (Pattern A) or that python -m finstatement_mcp works in the configured cwd (Pattern B).
• Run the command manually in a terminal to see the error.

"Tool calls return 401"

• Credentials are wrong, or the user account doesn't have access to the resource. Try logging into the web app with the same credentials.

"Tool calls return 422"

• Likely a wrong id (e.g. period_id doesn't belong to that company_id). Use list_periods(company_id) first.

"Tool calls hang"

• Backend is asleep on Railway free tier. Hit /health first, or run the backend locally.

Roadmap

Phase	Scope
0.1 (this)	Read-only tools, stdio transport, JWT auth
0.2	Streamable-HTTP transport (so the prod backend can host the MCP directly)
0.3	OAuth flow for ChatGPT Desktop + remote MCP clients
0.4	Mutating tools (post journal, run consolidation, approve mapping) — gated, audit-logged, with confirmation prompts in tool descriptions
0.5	Per-workspace API keys; per-tool RBAC

Privacy note

Tool results flow through the LLM provider's inference (Anthropic, OpenAI, etc.). Trial balance and consolidated statement data is sensitive — clients should opt in per workspace and understand which data leaves their tenant when MCP is enabled. This is a product/policy concern more than a technical one; document it clearly when shipping to clients.