# Finance MCP Server

A [Model Context Protocol](https://modelcontextprotocol.io) server exposing
personal-finance tools — accounts, transactions, spending analysis, budgets,
bills, reminders, portfolio, and goals — so **any MCP client** (Claude
Desktop, Claude Code, custom agents) can query financial data through a
standard interface.

The tool layer is shared with
[finance-copilot](https://github.com/arunkonapala/finance-copilot): same
deterministic sample dataset, same eight tools, different transport — there
they're wired into a bespoke agentic loop; here they're served over MCP.

## Tools

| Tool | Purpose |
|---|---|
| `get_accounts` | Balances across checking/savings/credit/brokerage/401(k) + net worth |
| `get_transactions` | Individual transactions, filterable by month and category |
| `analyze_spending` | Per-category monthly totals, trends, top merchants |
| `get_budgets` | Budget vs. actual for the current month with over/under status |
| `get_bills` | Recurring bills with next due dates and due-soon flags |
| `set_bill_reminder` | Create a reminder N days before a bill is due |
| `get_portfolio` | Holdings, gains/losses, asset allocation |
| `get_financial_goals` | Savings goals with progress + income/risk profile |

## Setup

```bash
python3 -m venv .venv && .venv/bin/pip install -r requirements.txt
.venv/bin/python test_client.py   # smoke test: lists tools, calls three
```

> If `pip` tries to compile `cryptography` from source (Anaconda x86_64
> Python without a matching wheel), create the venv with
> `python3 -m venv .venv --system-site-packages` to reuse the system copy.

## Connect a client

**Claude Code:**

```bash
claude mcp add finance -- /path/to/finance-mcp-server/.venv/bin/python /path/to/finance-mcp-server/server.py
```

**Claude Desktop** (`claude_desktop_config.json`):

```json
{
  "mcpServers": {
    "finance": {
      "command": "/path/to/finance-mcp-server/.venv/bin/python",
      "args": ["/path/to/finance-mcp-server/server.py"]
    }
  }
}
```

Then ask: *"How am I tracking against my budget this month?"* — the client
discovers the tools automatically and the model calls them as needed.

## Design notes

- **FastMCP** generates tool schemas from Python type hints and docstrings —
  the schemas stay in sync with the code by construction.
- **stdio transport** — the client spawns the server as a subprocess; no
  ports, no network exposure.
- **Demo data** — `finance_data.py` generates a deterministic fake bank
  (fixed seed). Swap it for a real aggregator (e.g. Plaid) to serve live
  data; the MCP surface doesn't change.
- `test_client.py` doubles as a minimal example of driving an MCP server
  programmatically with the Python SDK.