Expense Budget Tracker

What Expense Budget Tracker MCP server does

The Expense Budget Tracker MCP server gives AI agents controlled access to financial workspaces managed by Expense Budget Tracker. The underlying application provides budgeting and transaction views, account balances, transfers, and multi-currency reporting on Postgres. Agents can inspect workspace data and, when authorized, modify it through constrained SQL operations.

The hosted MCP endpoint is available at https://mcp.expense-budget-tracker.com/mcp. A separate Agent API provides HTTP access with API-key authentication, but its credentials cannot be used for the MCP connector. The project is open source and can also be deployed on infrastructure you control.

How it works

An MCP client connects over Streamable HTTP and completes OAuth authorization using authorization code flow with PKCE and Dynamic Client Registration. The signed-in user receives the expenses:read scope for workspace discovery, schema inspection, guidance retrieval, and read queries. The expenses:write scope is additionally required for data changes.

Queries use a restricted SQL interface. Read operations accept one SELECT or WITH ... SELECT statement. Write operations accept one approved INSERT, UPDATE, or DELETE statement. The available schema, constraints, SQL dialect, writing rules, and query examples can be requested through dedicated tools before an agent acts.

Setup and configuration

For hosted access, configure an MCP-compatible client with the endpoint and complete its OAuth flow. The service uses the MCP Registry identity com.expense-budget-tracker/expense-budget-tracker.

To run the application locally, clone the repository, start Docker, and run make up. This starts Postgres, applies migrations, and launches the web and worker services. The local stack is unauthenticated and binds to loopback by default. Runtime settings can be changed by copying infra/docker/.env.example to infra/docker/.env; the authenticated AWS deployment uses a different setup under infra/aws.

Tools and capabilities

The Expense Budget Tracker MCP server exposes five tools:

• list_workspaces lists workspaces available to the authenticated user.
• get_schema describes allowed relations, columns, constraints, and limits.
• get_guide returns protocol guidance for SQL syntax, writes, or query recipes.
• sql_query runs a single restricted read statement.
• sql_execute runs a single authorized data-changing statement.

The Agent API can also accept screenshots, CSV files, or PDF bank statements for transaction extraction, but that workflow belongs to the API and chat runtime rather than the MCP tool set.

Limitations and notes

Read and write permissions are separate. A client with only expenses:read cannot call sql_execute, and MCP OAuth access cannot be substituted with an Agent API ApiKey.

The hosted service handles financial workspace data. The project documentation states that, in the AWS/CDK deployment, chat transcript state is stored in Postgres, chat requests are sent to OpenAI, and telemetry is exported to Langfuse Cloud. Self-hosting is the documented option for greater control over deployment and data handling.

The MCP connector is intended for compatible remote MCP clients. The repository names Claude Code and Codex for the separate Agent API workflow, not as MCP-specific client configuration examples.