Breadbox

Self-hosted financial data store with an MCP server.

What it is

Breadbox aggregates bank transactions into a PostgreSQL database you control and exposes them over a REST API and an MCP server. The intent is infrastructure: one normalized data store that AI agents, dashboards, and scripts can all query without each tool needing your bank credentials.

• MCP server at /mcp (Streamable HTTP) and breadbox mcp (stdio), scoped API keys with per-tool read/write permissions
• REST API under /api/v1/*, specified in openapi.yaml
• Built-in agent runtime — schedule Claude Agent SDK runs on cron / sync-complete / on-demand, with per-run cost + turn caps and full NDJSON transcripts. Bring your own Anthropic API key or OAuth subscription token.
• Pluggable bank sync — a normalized provider interface; integrations and CSV import ship today, more on the roadmap
• Admin dashboard — transaction review queue, rule engine, sync monitoring, multi-user household support

Quick start

curl -fsSL https://breadbox.sh/install.sh | bash

Detects OS, installs Docker if needed, prompts for an optional public domain, generates secrets, and brings up the stack. Visit http://localhost:8080/setup (or your domain) to create the admin account.

Full install docs — binary download, Go source, manual Docker, daemon registration: docs.breadbox.sh/install.

Or deploy to a managed platform

One-click templates provision Postgres + a persistent volume + an auto-generated encryption key:

 

• Railway — fully one-click. Provisions everything, no prompts. ~2 minutes.
• Render — one-click Blueprint; paste a hex encryption key once during setup. ~2 minutes.

Both pull the prebuilt ghcr.io/canalesb93/breadbox image and inject $PORT automatically — no extra config.

CLI

The same breadbox binary doubles as a gh-style CLI for driving any Breadbox instance — locally or remote — over its REST API. Per-host credentials live in ~/.config/breadbox/hosts.toml; switch hosts with --host <name> or BREADBOX_HOST=<name>.

Already have a Breadbox server somewhere and just want the CLI on your laptop? Install only the 10 MB lite build — no Docker, no Postgres:

curl -fsSL https://breadbox.sh/cli.sh | bash

Detects your OS, drops breadbox into ~/.local/bin (or /usr/local/bin under sudo), and prompts for the host URL to connect to.

Local (same machine as the server)

breadbox auth bootstrap           # mint a full-access key, save to hosts.toml
breadbox doctor                   # readiness report
breadbox transactions list --limit 10
breadbox connections link --provider=plaid --user=<short_id> --wait

Remote (device-code login)

breadbox auth login --host=https://breadbox.example.com
# prints a verification URL + short code; approve on the server's /auth/device page
breadbox accounts list

Output is a human table on a TTY and JSON when piped, so breadbox transactions list | jq '.[].amount' just works. Full command catalog: docs/cli-commands.md.

A 10 MB breadbox-cli lite build ships separately for remote agents and scripts that don't need the server packages.

AI agents

Point any MCP client at https://your-host/mcp with an API key. Read transactions, apply categories, write rules, surface anomalies — without the agent ever touching bank credentials.

Claude Desktop / Claude Code config:

{
  "mcpServers": {
    "breadbox": {
      "command": "/path/to/breadbox",
      "args": ["mcp"],
      "env": {
        "DATABASE_URL": "postgres://breadbox:breadbox@localhost:5432/breadbox?sslmode=disable"
      }
    }
  }
}

Or let Breadbox run the agents itself: the built-in runtime ships with five starter agents (Initial Setup, Bulk Review, Quick Review, Routine Review, Spending Report) and a prompt builder for your own. See the multi-agent reviewer guide.

Status

Pre-1.0. Breaking changes are documented in CHANGELOG.md. Provider credentials are encrypted at rest with AES-256-GCM; the whole stack runs as a single Go binary alongside Postgres.

Documentation

• docs.breadbox.sh — install, providers, agents, API
• docs/ in this repo — engineering specs (data model, architecture, MCP tools, rule DSL)
• CONTRIBUTING.md — development setup

License

AGPL-3.0