Expense Budget Tracker MCP server

Expense Budget Tracker

Self-hosted open-source expense and budget tracker with balances, transfers, and multi-currency reporting on Postgres.

Live demo: expense-budget-tracker.com

Features

• Fully open-source — all code is available, deploy on your own servers with full control over your data
• Hosted MCP server — connect a compatible remote MCP client over Streamable HTTP and OAuth to query workspace data, with optional write access controlled by scope
• SQL Query API — generate an API key, give it to your LLM agent, and let it query, analyze, and manage your financial data via HTTP. Minimal, flat table structure designed to be hard to misuse — ideal for AI agents
• Budget and transaction UI — built-in interface for budgeting, browsing transactions, and tracking balances across accounts and currencies

Quick start

git clone https://github.com/kirill-markin/expense-budget-tracker.git
cd expense-budget-tracker
open -a Docker   # start Docker if not running (macOS)
make up          # start Postgres, run migrations, start web + worker

Open http://localhost:3000.

Usage with AI agents

Connect through either the hosted MCP server or the direct Agent API. Their credentials are separate and are not interchangeable: MCP uses OAuth Bearer access, while the Agent API uses an ApiKey.

MCP connector

The hosted MCP server is available directly at https://mcp.expense-budget-tracker.com/mcp. Its canonical MCP Registry identity is com.expense-budget-tracker/expense-budget-tracker; it is published there, and each later version becomes available only after its own manual publication workflow succeeds and exact-version verification completes. It exposes five OAuth-secured tools:

• list_workspaces — list workspaces available to the signed-in user
• get_schema — inspect the allowed relations, columns, constraints, and limits
• get_guide — fetch the SQL-dialect, writing-data, or query-recipes protocol before acting
• sql_query — run one restricted SELECT or WITH...SELECT
• sql_execute — run one approved INSERT, UPDATE, or DELETE

Compatible remote MCP clients authenticate with OAuth authorization code + PKCE and Dynamic Client Registration. The required expenses:read scope enables the four read tools; a client may also request expenses:write, which is required for sql_execute.

• MCP connector guide
• Agent API reference
• Privacy
• Support

Agent API

Start at GET https://api.expense-budget-tracker.com/v1/. The discovery response tells agents to ask for the user's email first, and the same email OTP flow covers both signup and login.

1. Open GET https://api.expense-budget-tracker.com/v1/ in your agent — it will discover the OTP onboarding flow automatically
2. Complete email OTP login — the auth service returns a long-lived ApiKey
3. Give the key to your AI agent — Claude Code, Codex, or any agent that can call HTTP APIs
4. Send the agent screenshots, CSV files, or PDF bank statements — it parses them and inserts transactions through the single-statement SQL execute endpoint
5. Open the web UI — view actual spending by category and plan the budget for the next month

For readonly work, agents send one SELECT or WITH...SELECT statement to the primary query endpoint:

curl -X POST https://api.expense-budget-tracker.com/v1/sql/query \
  -H "Authorization: ApiKey ebta_..." \
  -H "X-Workspace-Id: workspace-id" \
  -H "Content-Type: application/json" \
  -d '{"sql": "SELECT ts, amount, currency, category FROM ledger_entries ORDER BY ts DESC LIMIT 20"}'

Shortened. The full README is on GitHub.