budget-mcp

Track personal finances by talking to an LLM.An MCP server that gives any MCP-compatible client typed tools to log transactions, manage a category library, and analyse spending — plus interactive dashboards rendered directly in the chat client.

Built with Python,FastMCP, SQLAlchemy, SQLite and PostgreSQL.

Chat is a good interface for expense logging. "Spent £42 at Tesco and £8 on coffee" is faster than opening an app and filling in two forms, and an LLM can categorise it for you.

The problem is that an LLM with no tools will happilytellyou it logged your transaction. Getting this to work means the model must be unable to confuse "I recorded this" with "I described recording this" — so the tools have to return unambiguous success or failure, reject bad input rather than coercing it, and expose enough query surface that the agent reads real state instead of reconstructing it from conversation history.

That design problem is the actual point of this repo. The budgeting is the excuse.

🧠 Design notes: making agent calls trustworthy

Explicit failure over silent coercion.Tools validate input and return a structured error naming what was wrong, rather than guessing at intent. An invalidtype, a malformed date, or acategory_idthat doesn't exist fails loudly, so the agent can correct itself and report accurately to the user instead of inventing a confirmation.

Batch-first write tools.add_transaction,update_transaction,delete_transactionandadd_categoryall accept either a single item or anitemslist. Agents naturally handle several things at once ("log these five expenses"), and forcing them into one call per record multiplies both latency and the number of places a partial failure can hide.

Referential integrity at the tool boundary.delete_categorytakes an optionalreassign_to_category_id, so removing a category can't silently orphan its transactions. The integrity decision is surfaced as a parameter the agent must reason about rather than a side effect it discovers later.

Read surface sized for multi-turn use.get_summary,get_transactionsandget_uncategorized_transactionscover aggregate, detail and triage reads with consistent filter arguments across all three.get_uncategorized_transactionsreturns results sorted by description specifically so an agent can categorise bulk imports in coherent groups instead of one row at a time.

Idempotent schema bootstrap.Tables and 15 default categories are created on first startup, so a fresh clone or a new cloud deployment is immediately usable and there's no partially-initialised state for a tool call to land in.

- Local or cloud storage— zero-setup SQLite (in-memory ordata/budget.db), or PostgreSQL via any provider such as Neon.
- Interactive dashboards in-client— category pie charts and searchable transaction tables rendered viaprefab-ui, returned as MCP UI apps rather than plain text.
- Spending trends— continuous category line chart with month/week/day granularity toggle, date-range slider and searchable table.
- Batch operations— single-item or bulk write across transactions and categories.
- Reproducible environment—uvfor fast, locked dependency resolution.
- Broad client support— Claude Desktop, Claude Code, Cursor, Goose, Open WebUI, and any other MCP host.

git clone https://github.com/PedroLiu1999/budget-mcp.git cd budget-mcp uv sync uv run pytest # confirm the install works uv run server.py # start the server (in-memory SQLite by default)

Then register it with your client — Claude Code is the one-liner:

claude mcp add budget -- uv run --directory "/absolute/path/to/budget-mcp" server.py

To persist data, setDATABASE_URLin a.envfile first (seeDatabase configuration).

DATABASE_URL=postgresql://<user>:<password>@<hostname>/<dbname>?sslmode=require

claude mcp add budget -- uv run --directory "/absolute/path/to/budget-mcp" server.py

{ "mcpServers": { "personal-budget": { "command": "uv", "args": ["run", "--directory", "/absolute/path/to/budget-mcp", "server.py"] } } }

Settings → Features → MCP → Add New MCP Server

- Type:command
- Name:budget-mcp
- Command:uv run --directory "/absolute/path/to/budget-mcp" server.py

Bridge the stdio server over HTTP withmcpo:

uvx mcpo --port 8000 -- uv run server.py

Then inAdmin Panel → Settings → External Tools, add the OpenAPI connection URLhttp://localhost:8000(orhttp://host.docker.internal:8000from Docker).

For remote hosts, Docker, or platforms such as Horizon:
- SetDATABASE_URLto a cloud PostgreSQL connection string in the deployment environment — in-memory SQLite will not persist across restarts.
- Point the runner at the ASGI app:

fastmcp run server.py:mcp

Schema tables and default categories initialise on import, so no migration step is needed on first boot.

Inspect tools interactively with the FastMCP Inspector:

uv run fastmcp dev inspector server.py:mcp

Or preview interactive UI applications directly in the browser:

Bridge Town is an MCP-native, git-versioned financial modeling platform for FP&A teams and finance leaders. AI agents use Bridge Town tools to create projects, write Python model files, run models in isolated cloud sandboxes, query data, write outputs to Google Sheets, create dashboards, branch scenarios, and collaborate with teammates.

The Capital.com MCP Server lets your AI assistant talk to your trading account directly. Market data, position checks, trade previews – all in plain language, without leaving your AI tool.

Coinrule Agentic Trading MCP enables investors to create, backtest, execute, and manage trading agents through natural language across stocks, crypto and ETFs

Invest with Claude and other AI assistants

Australian Consumer Data Right Product Data

Remote MCP server for historical crypto & prediction-market data: search ~500K instruments, live market stats (OHLC, turnover, spreads, depth, slippage) and tick-data purchase. Keyless for catalog & stats; optional OAuth for account tools. Endpoint: https://cryptostruct.com/mcp

Cross-border debt collection from your AI assistant: check cases, get pricing, submit new cases.

Read-only MCP server for your Evibe investment portfolio + live market data (holdings, performance, dividends, benchmarks, screeners). Works with Claude & ChatGPT.

Financial and quantitative modeling engine for AI agents. Typed, named, deterministic.