InvoiceMCP

MCP server giving AI agents read access to subscription/SaaS invoice history, ingested from Gmail and normalized into Postgres (structured data) + MongoDB (PDFs). See SPEC.md for the full design.

Prerequisites

• Node 22+, pnpm

• Docker (local Postgres/Mongo/Redis) — or Railway database URLs

• Google OAuth client (Gmail API enabled, redirect URI http://localhost:8787/oauth/callback)

• OpenRouter API key

Related MCP server: ntriq-agentshop

Setup

1. cp .env.example .env and fill in values (scripts/ has key generators noted inline)

2. docker compose up -d

3. pnpm install

4. pnpm migrate up — applies migrations/ to Postgres

5. pnpm cli seed-org --name "Your Org"

6. pnpm cli auth — browser OAuth consent, stores encrypted refresh token

7. pnpm cli check-connections — sanity check all three databases

Running

MCP tools

list_services, list_invoices, get_invoice, get_invoice_pdf, spend_summary — all scoped to DEFAULT_ORG_ID; money in minor units, per-currency aggregation, no FX conversion.

Claude Desktop's connector UI expects OAuth, which this MVP doesn't implement — bridge with mcp-remote in claude_desktop_config.json instead:

{
  "mcpServers": {
    "invoice-mcp": {
      "command": "npx",
      "args": [
        "-y", "mcp-remote", "https://<host>/mcp",
        "--header", "Authorization: Bearer <MCP_API_KEY>"
      ]
    }
  }
}

Development

• pnpm test / pnpm typecheck / pnpm lint

• pnpm codegen — regenerate src/db/types.ts after schema changes

• tsx scripts/smoke-extract.ts [pdf] — live LLM extraction smoke test

• tsx scripts/make-fixture-pdf.ts — regenerate the multi-page fixture PDF

Deploy (Railway)

One repo, two services:

• worker — start pnpm start:worker

• mcp — start pnpm start:mcp (health check /healthz)

Both build with pnpm install && pnpm build. Run pnpm migrate up as the worker's pre-deploy command. Set env vars per .env.example (Railway injects database URLs for linked Postgres/Mongo/Redis services).