crunch-mcp

Open source · MIT · Model Context Protocol

Talk to your Crunch books.

crunch-mcp connects Claude and other AI assistants to Crunch Accounting. Ask about expenses, invoices, clients and bank accounts in plain English, and let the assistant record receipts and raise invoices when you allow it.

Get started Star on GitHub
docker pull ghcr.io/mattoddie/crunch-mcp
Claude · crunch
Which invoices are overdue, and who should I chase?
crunch_list_invoicesall · unpaidcrunch_get_invoiceINV-0042crunch_get_clientAcme Ltd
Three invoices are overdue, £7,140 in total. The one to chase is INV-0042 toAcme Ltd: £5,400 for August's consulting, now 34 days late with no payment recorded.

The other two are only 4 and 6 days late. Shall I send Acme a copy with a friendly reminder?
Yes please, keep it polite.
Sent. Acme's accounts team has INV-0042 again, with a short note that it was due on 11 September. When they pay, tell me the date and I'll record the payment. ✅
70tools
9toolsets
6guided prompts
~21 MBdistroless image

Ask anything

Your books, in plain English.

The assistant picks the right tools, runs them against Crunch's public API and explains what it found. No exporting spreadsheets or clicking through screens to find a number.

“Record this receipt from the train station.”

list_expense_typeslist_supplierscreate_expense

“Which invoices are overdue and who should I chase?”

list_invoicesget_clientemail_invoice

“How much did I spend on software this year?”

list_expense_typesget_expenses_total

“Create an invoice for Acme for 5 days at £450.”

list_clientslist_vat_typescreate_invoice

“Give me a summary of last quarter.”

get_invoice_totalsget_expenses_totallist_bank_accounts

“Are there any expenses missing receipts?”

list_expensesget_expense

Full coverage

70 tools across Crunch's public API.

Grouped into 9 toolsets you can switch on and off, so the assistant only sees what you need: 36 read, 24 write, 9 delete and 1 email tool.

account6

Login status and the OAuth login flow, the logged-in user, company details (VAT number and scheme, addresses) and a one-call business overview.

reference6

Lookups for the values Crunch expects: expense types, VAT types, payment methods, countries, open accounting periods, and directors and employees.

banking17

Bank accounts and credit cards: balances, details, payments recorded against them, opening balances, default accounts, archiving.

clients5

Clients (the customers you invoice): list, look up, create, update and delete.

suppliers5

Suppliers (who you buy from): list, look up, create, update, archive and delete.

expenses10

Expenses: list and filter, totals, create with lines, payments and receipts, update, record and remove payments, attach and download receipts, delete.

recurring5

Recurring expenses that Crunch creates on a schedule: list, create, pause or change, delete.

invoices15

Sales invoices: list and filter, totals, create drafts, update, issue, email to the customer, record and remove payments, attachments, PDF download, delete.

raw1

A raw API escape hatch for anything the other tools don't cover. It is limited to GET requests unless writes are enabled.

read write delete email ·Full tool reference →

Safe by default

It can look. It only touches your books when you say so.

Tools that aren't allowed aren't registered at all. The assistant can't see them, so it can't call them or be talked into calling them.

  • Read-only out of the box. Writes, deletes and emailing your customers are three separate switches.
  • Least-privilege OAuth scopes. Login asks Crunch only for what your settings need, so a read-only setup gets a read-only token.
  • Destructive tools are labelled, so your client asks before running them.
  • Bearer-token auth, a Host allow-list and a read-only, non-root container.
Read the security model →
read

36 tools, always on

list_invoices · get_expenses_total · get_overview …
write

24 tools with CRUNCH_ALLOW_WRITES=true

create_expense · create_invoice · issue_invoice · add_invoice_payment …
delete

9 tools with CRUNCH_ALLOW_DELETES=true as well

delete_expense · delete_invoice · remove_invoice_payment …
email

1 tool with CRUNCH_ALLOW_EMAIL=true as well

email_invoice, which sends invoices to your customers

Built with care

The fiddly parts, handled.

Accounting data has to be right. crunch-mcp is careful about how it logs in, how it changes records and how it's tested.

Docker-first

A ~21 MB distroless image for amd64 and arm64. It runs as non-root on a read-only filesystem, and only the token volume is writable.

OAuth handled

Log in once with OAuth 2.0 and PKCE. Crunch rotates refresh tokens, so each new one is written safely to the volume and survives restarts.

Careful updates

Changes are read-modify-write: the current record is fetched and merged first, so Crunch never drops an expense's payments or attachments.

Receipts and PDFs

Attach receipt photos or PDFs to expenses and invoices, download them again, and fetch any sales invoice as a PDF.

Lookups built in

Expense types, VAT types, payment methods and open accounting periods are one call away, so the assistant uses values Crunch accepts.

Tested against a mock Crunch

The test suite runs the tools against a mock Crunch API, so changes are checked without going anywhere near real books.

6 guided prompts turn common jobs into one step. In Claude Code they're slash commands, such as /mcp__crunch__record_receipt.

  • business_health_check
  • chase_overdue_invoices
  • create_invoice
  • expense_review
  • period_summary
  • record_receipt

Works with your Crunch account

Crunch's public API, end to end

  • Expenses & receipts
  • Sales invoices
  • Clients
  • Suppliers
  • Recurring expenses
  • Bank accounts
  • Credit cards
  • Company & VAT details

Uses your own Crunch API access and logs in to your account with OAuth. When a tool doesn't cover something, a raw API tool does, limited to reads unless writes are on. Compatibility →

Works with your assistant

Streamable HTTP or stdio

  • Claude Code
  • Claude Desktop
  • VS Code
  • Cursor
  • Codex
  • Any MCP client

Run it once and share it, or start it per session with docker run -i. You can even log in from the chat with the auth tools. Client setup →

Quick start

Up and running in three steps.

  1. 1

    Get Crunch API access

    Apply at developer.crunch.co.uk. Crunch emails you a client ID, and a client secret if your client is confidential.

  2. 2

    Log in and start it

    mkdir crunch-mcp && cd crunch-mcp
curl -fsSLO https://raw.githubusercontent.com/mattoddie/crunch-mcp/main/compose.yaml
curl -fsSL https://raw.githubusercontent.com/mattoddie/crunch-mcp/main/example.env -o .env
# set CRUNCH_CLIENT_ID (and CRUNCH_CLIENT_SECRET
# if you have one) and MCP_AUTH_TOKEN in .env
docker compose run --rm -p 8976:8976 crunch-mcp login
docker compose up -d
  3. 3

    Connect your assistant

    claude mcp add --transport http crunch \
  http://<docker-host>:8080/mcp \
  --header "Authorization: Bearer <token>"

    Then ask: “How's the business doing this month?”

Ready to talk to your books?

Free, open source and MIT licensed. Contributions and bug reports are welcome.

Read the docs Contribute