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