Metadata-Version: 2.4
Name: finstatement-mcp
Version: 0.2.0
Summary: MCP server for FinStatement Pro — read-only financial statement queries via Claude, ChatGPT, Cursor, and other MCP clients. 23 tools across companies, periods, trial balances, account mappings, statements, and consolidations.
Project-URL: Homepage, https://github.com/suhitdasmahapatra/BRD-Software-
Project-URL: Source, https://github.com/suhitdasmahapatra/BRD-Software-/tree/main/6_mcp
Project-URL: Issues, https://github.com/suhitdasmahapatra/BRD-Software-/issues
Project-URL: Documentation, https://github.com/suhitdasmahapatra/BRD-Software-/blob/main/6_mcp/README.md
Author-email: Suhit Das Mahapatra <suhitdasmahapatra@gmail.com>
License: MIT License
        
        Copyright (c) 2026 Suhit Das Mahapatra
        
        Permission is hereby granted, free of charge, to any person obtaining a copy
        of this software and associated documentation files (the "Software"), to deal
        in the Software without restriction, including without limitation the rights
        to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
        copies of the Software, and to permit persons to whom the Software is
        furnished to do so, subject to the following conditions:
        
        The above copyright notice and this permission notice shall be included in all
        copies or substantial portions of the Software.
        
        THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
        IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
        FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
        AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
        LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
        OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
        SOFTWARE.
License-File: LICENSE
Keywords: chatgpt,claude,consolidation,cursor,financial-statements,finstatement,ind-as,mcp,model-context-protocol
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Financial and Insurance Industry
Classifier: Intended Audience :: Information Technology
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Office/Business :: Financial :: Accounting
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Classifier: Typing :: Typed
Requires-Python: >=3.10
Requires-Dist: httpx>=0.27.0
Requires-Dist: mcp[cli]>=1.0.0
Requires-Dist: python-dotenv>=1.0.0
Description-Content-Type: text/markdown

# 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.
**23 tools** — 22 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` |
| Account mappings | `list_account_mappings`, `list_unmapped_accounts`, `suggest_account_mappings` |
| 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)

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

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

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

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

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

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

```env
FINSTATEMENT_BASE_URL=http://localhost:8000
FINSTATEMENT_EMAIL=you@example.com
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:

```json
{
  "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.

```json
{
  "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:

```json
{
  "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.
