bookie

An MCP server that keeps books for freelancers and landlords — driven from Claude or GPT instead of QuickBooks.

Ask your LLM to import a bank statement, categorize spending, reconcile a month, or generate a Schedule C. Bookie provides the correct double-entry ledger underneath — so the model reasons over real numbers, not a spreadsheet it's improvising on the fly.

This is for you if: you're a solopreneur, freelancer, or rental property owner already living in Claude or GPT, you're comfortable with a 5-minute setup, and you want books that are actually correct.

Not for you if: you want a dashboard UI, you need multi-user access, or you're satisfied with QuickBooks / a spreadsheet.

What you need before starting

• Node ≥ 24
• **neonctl** — `npm install -g neonctl` (free Neon account; needed for the DB)
• An MCP-capable host: Claude Desktop, Claude.ai, Cursor, VS Code, or any host supporting the MCP stdio or HTTP transport

Quick start (local, stdio)

Recommended — from source, fully automated:

git clone https://github.com/yuens1002/bookie
cd bookie
npm install
npm run setup   # creates Neon DB, generates secrets, writes .env, runs db:push
npm run build

`npm run setup` opens a browser to log into Neon; new to Neon? Use the "Sign up for an account" link and pick GitHub/Google/Microsoft rather than email+password — it completes in the same browser round-trip, no email-verification detour that could interrupt the CLI mid-wait.

`npm run setup` prints a ready-to-paste Claude Desktop config block at the end:

{
  "mcpServers": {
    "bookie": {
      "command": "node",
      "args": ["/absolute/path/to/bookie/dist/index.js"],
      "env": {
        "BOOKIE_DB_URL": "",
        "BOOKIE_DB_DIRECT_URL": "",
        "BOOKIE_API_KEY": ""
      }
    }
  }
}

Adding another machine to the same ledger — no clone needed: stdio is a *local* process — every machine running a stdio MCP client spawns its own copy of the server, so each one otherwise needs its own checkout. Once the Neon DB is provisioned (via `npm run setup` above, on any one machine), every *other* machine just needs the same connection strings — no `git clone`, no `npm install`, no `npm run build` to keep in sync. Point that machine's MCP host at the published package instead:

{
  "mcpServers": {
    "bookie": {
      "command": "npx",
      "args": ["-y", "bookie-mcp"],
      "env": {
        "BOOKIE_DB_URL": "",
        "BOOKIE_DB_DIRECT_URL": "",
        "BOOKIE_API_KEY": ""
      }
    }
  }
}

`npx` fetches and runs the published version on demand — every machine pointed at the same `BOOKIE_DB_URL` shares one ledger, without any of them (besides the original) needing a checkout.

Bootstrapping a DB without cloning at all: if you don't have connection strings yet from any machine (e.g. you created the Neon project manually instead of via `npm run setup`), push bookie's bundled schema directly:

mkdir bookie-mcp && cd bookie-mcp
npm install bookie-mcp
BOOKIE_DB_URL= BOOKIE_DB_DIRECT_URL= npx prisma db push --schema=node_modules/bookie-mcp/prisma/schema.prisma

Then use the same `npx -y bookie-mcp` config above.

Quick start (remote, HTTP — for Claude.ai mobile)

Deploy to Railway with one click:

Railway pulls the pre-built image from GHCR — no source build needed. Set the required env vars when prompted. See docs/DEPLOYING.md for the full walkthrough (env var reference, Neon + Resend setup, Claude.ai OAuth connector).

Why no UI?

The host LLM already reads CSVs, sees receipt images, and writes prose. Bookie owns the things an LLM *shouldn't* improvise: a correct double-entry ledger, integer-cent money math, deterministic categorization rules, and reproducible reports. The model handles language and vision; the server handles the books.

Tools

The full, always-current tool reference lives in `docs/TOOLS.md` (regenerate with `npm run docs:tools`). Today:

Resources

Bookie exposes two MCP resources that an LLM can read without calling a tool:

Prompts

Three canned workflow prompts guide the LLM through common bookkeeping tasks:

Configuration

See `.env.example` for the full reference. Key variables:

Docs

• Architecture — data model, transports, layering
• Deploying — Railway + Neon + Resend setup
• Roadmap — phased plan
• Changelog — what shipped
• Releasing — versioning + release process
• Tools — generated manual
• Contributing — setup, conventions, tests

Safety

Bookie stores financial data in your Neon Postgres database; connection strings live in `.env` (gitignored) and Railway env vars — never commit them. The HTTP transport requires auth on every `/mcp` request: either a static Bearer token (`BOOKIE_API_KEY`) or an OAuth JWT issued by the `/token` endpoint. Always set at least one before exposing the server beyond localhost. See docs/DEPLOYING.md for the full Claude.ai connector OAuth setup.

License

MIT