mcp-server-billing

MCP server that gives an AI agent guarded access to a B2B SaaS billing database (customers, subscriptions, invoices, credit notes) and live ECB exchange rates. Six tools: five reads covering the whole billing surface, one carefully fenced write. Runs locally over stdio against docker-compose Postgres, or on AWS behind a Lambda Function URL for about $7.67/month.

Full design rationale, protocol-version notes, and every decision's trade-off: SPEC.md. Implementation conventions and the code review checklist: CODING_STYLE.md.

Tools

Tool	Purpose	Read-only	Idempotent
billing_search_customers	Find customers by name, email, domain, status, country	✓	✓
billing_get_customer	One customer with subscriptions and open balance	✓	✓
billing_list_invoices	Invoices filtered by customer, status, date range	✓	✓
billing_revenue_summary	Monthly MRR/ARR, new vs. churned, by plan or country	✓	✓
billing_convert_currency	Convert an amount via live ECB rates (frankfurter.dev)	✓	✗
billing_issue_credit_note	The one write. Credit an open invoice, capped and idempotency-keyed	✗	✓

Plus one resource (billing://schema, the live DDL) and one prompt (revenue_review, a guided monthly review). Full schemas, annotations, and example calls: SPEC.md §5.

Run it (60 seconds)

docker compose up -d && npm run db:seed
npm run build
cp .env.example .env   # fill in MCP_BEARER_TOKEN if you'll also try http/lambda
npm run inspect

The Inspector opens in your browser against the six tools, live, against seeded data (~200 customers, ~2,000 invoices). Requires Node ≥22.19 for the Inspector itself (this repo's own code targets Node ≥20 — the gap is the Inspector CLI, not the server; see SPEC.md §9 for what was verified without it).

Wire it to Claude Desktop

{
  "mcpServers": {
    "billing": {
      "command": "node",
      "args": ["/absolute/path/to/mcp-server-aws/dist/stdio.js"],
      "env": {
        "DATABASE_URL_READER": "postgres://mcp_reader:reader_local_pw@localhost:5434/billing",
        "DATABASE_URL_WRITER": "postgres://mcp_writer:writer_local_pw@localhost:5434/billing"
      }
    }
  }
}

Use an absolute path — Claude Desktop does not resolve ~ or relative paths.

Deploy to AWS

npm run lambda:prepare                 # builds + stages dist/ + prod deps + db/init/*.sql
cd terraform
cp terraform.tfvars.example terraform.tfvars   # fill in mcp_bearer_token
terraform init && terraform apply
terraform output -raw migrate_command | bash   # applies schema, rotates role passwords

	$/month
RDS db.t4g.micro, 11h/day (power-scheduled)	5.35
gp3 storage, 20 GB	2.30
Lambda + Function URL, VPC, SSM	~0.02
Total	≈ 7.67

No NAT Gateway: Lambda reaches frankfurter.dev over IPv6 through an egress-only internet gateway (verified live — Frankfurter has AAAA records) instead of a ~$32.85/month NAT Gateway. terraform destroy takes it to $0. Full cost breakdown and the architecture diagram: SPEC.md §3.

Eval questions

Five questions an agent should answer using only these tools — multi-tool, verifiable against the seed data, one deliberately negative (does the agent respect the credit cap, or try to split it?). SPEC.md §9.

Development

npm test              # unit + integration (needs docker compose up -d)
npm run lint           # eslint
npm run typecheck      # tsc --noEmit
npm run format:check   # prettier

Before opening a PR, run the code review checklist.