budget-mcp

💰 Personal Budget MCP Server

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.

Why this exists

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 happily tell you 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.

📸 Screenshots

Budget dashboard	Spending trends

🧠 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 invalid type, a malformed date, or a category_id that 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_transaction and add_category all accept either a single item or an items list. 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_category takes an optional reassign_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_transactions and get_uncategorized_transactions cover aggregate, detail and triage reads with consistent filter arguments across all three. get_uncategorized_transactions returns 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.

✨ Features

• Local or cloud storage — zero-setup SQLite (in-memory or data/budget.db), or PostgreSQL via any provider such as Neon.
• Interactive dashboards in-client — category pie charts and searchable transaction tables rendered via prefab-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 — uv for fast, locked dependency resolution.
• Broad client support — Claude Desktop, Claude Code, Cursor, Goose, Open WebUI, and any other MCP host.

🚀 Quickstart

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, set DATABASE_URL in a .env file first (see Database configuration).

🛠 Available tools

⚙️ Database configuration

Set via the DATABASE_URL environment variable in a .env file. Keep .env out of version control.

Local SQLite — in-memory (default if DATABASE_URL is unset):

DATABASE_URL=sqlite:///:memory:

Local SQLite file — persists between restarts:

DATABASE_URL=sqlite:///data/budget.db

PostgreSQL / Neon:

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

Tables and 15 default category seeds are created automatically on first startup.

🔌 Client setup

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"]
    }
  }
}

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

☁️ Cloud deployment

For remote hosts, Docker, or platforms such as Horizon:

1. Set DATABASE_URL to a cloud PostgreSQL connection string in the deployment environment — in-memory SQLite will not persist across restarts.
2. 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.

🧪 Testing

uv run pytest

Inspect tools interactively with the FastMCP Inspector:

uv run fastmcp dev inspector server.py:mcp

Or preview interactive UI applications directly in the browser:

uv run fastmcp dev apps server.py:mcp

📝 License

MIT — see LICENSE.