# Expense Budget Tracker

Self-hosted expense and budget tracker on Postgres with an OAuth MCP server and a SQL agent API.

A personal finance tracker built for agents: a flat Postgres schema, a hosted MCP server (list_workspaces, get_schema, sql_query, sql_execute) with OAuth scopes, and an API-key SQL endpoint so Claude Code or Codex can parse bank statements and insert transactions. MIT, deployable with Docker Compose or AWS CDK; a free hosted instance exists.

Alternative to: YNAB

- Capabilities: adaptable, operable
- Vertical: invoicing-finance
- Shape: product
- Form factor: web-app
- Execution model: deterministic
- Provenance: mixed (recorded, never ranked)
- Repo: https://github.com/kirill-markin/expense-budget-tracker (MIT), 30 stars, last commit 2026-09-02
- Last activity: 2026-09-02
- Page: apps/kirill-markin--expense-budget-tracker.html
- JSON: apps/kirill-markin--expense-budget-tracker.json

## Use it when

- I want my coding agent to file my expenses from bank exports with SQL it can inspect
- I want a budget tracker whose MCP works with any remote MCP client over OAuth

## Gotchas

- Authenticated mode requires AWS Cognito; AUTH_MODE=none is local-only
- The hosted instance sends chat data to OpenAI and Langfuse; the README says so plainly
- Real-software signal is thin: 30 stars, all 100 issues filed by the maintainer, no pricing on the hosted edition

## Editions

- Self-hosted: Free, open source
  - source: make up
- Hosted: Free, closed source
  - hosted: https://app.expense-budget-tracker.com

## Adaptable: make it yours

Effort: config-only (18 things to edit)

Local run is make up with the .env: three Postgres roles, AUTH_MODE none for local or cognito for anything public, OAuth issuer and MCP resource URLs, optional OpenAI and Langfuse for in-app chat. A public deployment follows the AWS CDK guide; server.json describes the MCP server for the registry.

- Env vars: DATABASE_URL, MIGRATION_DATABASE_URL, AUTH_DATABASE_URL, AUTH_MODE, HOST, CORS_ORIGIN, AUTH_DOMAIN, COOKIE_DOMAIN, OAUTH_ISSUER, OAUTH_RESOURCE, COGNITO_USER_POOL_ID, COGNITO_CLIENT_ID, SESSION_ENCRYPTION_KEY, OPENAI_API_KEY, RESEND_API_KEY
- Config files: .env, server.json, infra/aws
- Prompt files: none
- Accounts you'll need: AWS account with Cognito for an authenticated self-host; OpenAI (optional chat); Resend (email OTP on self-host)

## Operable: what an agent can drive

Operability: official. Interface: mcp at https://mcp.expense-budget-tracker.com/mcp (published by the builder, both).

### Reach (partial coverage)

- Record and query transactions: reachable. sql_query and sql_execute on ledger_entries (README curl examples)
- Balances and transfers across accounts: reachable. flat table schema exposed by get_schema; README feature list
- Budgets by category: reachable. budget tables reachable through sql_query; UI built on the same schema
- Multi-currency reporting: reachable. exchange_rates table filled by the worker; queries in SQL
- Import bank statements, screenshots and PDFs: reachable. README Agent API step 4: the agent parses files and inserts through the execute endpoint
- Workspace management: undetermined. list_workspaces and select exist; creating workspaces over MCP not documented
- Sign up and issue credentials: reachable. GET api.expense-budget-tracker.com/v1/ discovers the email OTP flow for agents

## Code stack

- Languages: TypeScript
- Frameworks: Next.js
- Package manager: npm
- Database: PostgreSQL
- Hosting target: Docker Compose, AWS (CDK, ECS, RDS, Cognito)

## Model stack

- Providers: OpenAI (optional in-app chat)
- Models: none
- Keys you need (names only): OPENAI_API_KEY, LANGFUSE_PUBLIC_KEY, LANGFUSE_SECRET_KEY
- Prompts live in: none
- Tools: none

## Evidence and confidence

- formFactor: web UI plus MCP and HTTP SQL API (README) (confidence 0.9)
- executionModel: tracker is deterministic; optional chat feature calls OpenAI (confidence 0.85)
- operability: MCP served on the Builder's domain and implemented in apps/sql-api per server.json; MCP Registry name com.expense-budget-tracker/expense-budget-tracker (confidence 0.9)
- effort: .env.example documents local and AWS variables; server.json in repo (confidence 0.8)
- editions: README and site: open source self-host plus hosted app; no pricing page found (confidence 0.7)
- active: GitHub pushedAt 2026-09-02; Show HN 2026-03-02; 1,052 commits
- reach:  (confidence 0.75)

## Open questions

- Gate 3 is borderline: passes on the Show HN thread and hosted product, but there is no external user evidence in issues; Curator to confirm
- Whether the hosted edition will stay free

## Sources

- https://github.com/kirill-markin/expense-budget-tracker (sourcing:invoicing-finance:community)
- https://expense-budget-tracker.com/docs/mcp-connector/ (analysis:invoicing-finance)
- https://github.com/kirill-markin/expense-budget-tracker/blob/main/server.json (analysis:invoicing-finance)