stripe-collections-mcp

Ask Claude who owes you money, and let it chase only the invoices you've cleared it to chase.

Results

• 11 tests passing. 4 tools: 3 read tools and 1 write tool with a gate.

• Safety checks: live key refused, writes off by default, re-check before send, audit log.

• Cost to run: $0 locally with Stripe test mode.

An MCP server that connects Stripe to Claude, ChatGPT, or any MCP client. It reads your open invoices, works out who's late and by how much, and can re-send an overdue invoice to the customer. It starts read-only, and sending stays off until you turn it on.

Related MCP server: NitroWatch Billing Demo

Demo

Tools

Safety

• Test mode only. A live Stripe key stops the server before it connects to anything.

• Read-only by default. send_invoice_reminder refuses to run unless the server was started with ALLOW_WRITES=true.

• It re-checks before it sends. The invoice has to still be open and actually overdue, or nothing goes out.

• Every call is logged. One JSON line per tool call, reads included, in ~/.stripe-collections-mcp/audit.jsonl. Set AUDIT_LOG to move it, or AUDIT_LOG=off to turn it off.

• Bad input never reaches Stripe. Customer and invoice ids are validated first.

• Use a restricted key. In Stripe, create a restricted key with Invoices: Read and Customers: Read. Add Invoices: Write only if you turn sending on.

Why the guardrails

• An agent that can send money-related emails needs a hard off switch.

• Invoice state can change between a recommendation and a send, so the server checks again before it sends.

• An audit trail makes each tool call reviewable.

Run it

Needs Node 20 or newer. Clone the repo, then:

npm install

npm install builds it. The server lives at dist/src/index.js.

Claude Desktop: add this to claude_desktop_config.json, then restart Claude.

{
  "mcpServers": {
    "stripe-collections": {
      "command": "node",
      "args": ["/absolute/path/to/stripe-collections-mcp/dist/src/index.js"],
      "env": {
        "STRIPE_API_KEY": "rk_test_...",
        "ALLOW_WRITES": "false"
      }
    }
  }
}

Claude Code:

claude mcp add stripe-collections -e STRIPE_API_KEY=rk_test_... -- node /absolute/path/to/stripe-collections-mcp/dist/src/index.js

Try it

• "Who owes me money right now?"

• "How much is more than 60 days late?"

• "How late does this customer usually pay?"

• "Send a reminder for every invoice more than 30 days late." (Needs ALLOW_WRITES=true. Your client will still ask before each send unless you've auto-approved the tool.)

Tests

npm test

11 tests call every tool through a real MCP client against a fake Stripe, so they never touch the network. They cover the sort order, the aging buckets, the late-payment math, sending blocked while writes are off, refusing invoices that are paid or not due yet, Stripe errors coming back as tool errors, and the live-key guard.

How it's built

• src/backend.ts: the only file that talks to Stripe. It flattens Stripe's invoice into the fields the tools need.

• src/server.ts: the four tools, the aging math, and the write gate.

• src/safety.ts: the test-mode key check and the audit log.

• src/index.ts: stdio entry point. Logs go to stderr because stdout carries the protocol.

Swapping Stripe for another billing API means rewriting backend.ts and nothing else.

Built by Vanwayne Chaney. I build custom MCP servers that connect your API to Claude and ChatGPT.