crunch-mcp
Server Configuration
Describes the environment variables required to run the server.
| Name | Required | Description | Default |
|---|---|---|---|
| CRUNCH_TOOLSETS | No | Optional comma-separated toolsets, e.g. account,reference,expenses. Empty means all but raw (list raw by name). | |
| CRUNCH_AUDIT_LOG | No | Optional audit log of every change: stderr, or a file path inside the container. Empty turns it off. | |
| CRUNCH_CLIENT_ID | Yes | The client ID Crunch gave you when it approved your API application. | |
| CRUNCH_FILES_DIR | No | Optional folder, inside the container, for receipts to attach and files to save. Mount it too. Empty turns it off. | |
| CRUNCH_ALLOW_EMAIL | No | Also allow emailing invoices and turning on payment reminders. Needs CRUNCH_ALLOW_WRITES. | false |
| CRUNCH_ALLOW_WRITES | No | Allow creating and changing records, including issuing invoices. Off means read-only. | false |
| CRUNCH_REDIRECT_URI | No | Only if your API account has a redirect URI registered with Crunch. Empty means http://127.0.0.1:8976/callback. | |
| CRUNCH_ALLOW_DELETES | No | Also allow deleting records and removing payments. Needs CRUNCH_ALLOW_WRITES. | false |
| CRUNCH_CLIENT_SECRET | No | Only for confidential clients, which Crunch issues a secret. Leave empty for a public client. | |
| CRUNCH_RAW_READ_ONLY | No | Keep the raw API tool to GET requests even when CRUNCH_ALLOW_WRITES is on. | false |
| CRUNCH_REFRESH_TOKEN | No | Optional refresh token to start from instead of logging in. Don't use it anywhere else afterwards. | |
| CRUNCH_RAW_ALLOWED_PATHS | No | Optional comma-separated path prefixes the raw API tool may use, e.g. /expenses. Empty allows all. |
Instructions
Guidance the server publishes about itself, which clients place ahead of the tool catalog so the model reads it before choosing anything.
Tools for Crunch Accounting (UK online accounting for freelancers, contractors and small limited companies): expenses and receipts, suppliers, recurring expenses, sales invoices, clients (customers), bank accounts, credit cards and company details. Start with crunch_get_overview for a snapshot of the business. If a tool says the server isn't logged in, use crunch_auth_start and crunch_auth_complete. Amounts are in GBP. Look up valid values before creating records: crunch_list_expense_types, crunch_list_vat_types, crunch_list_payment_methods, crunch_list_bank_accounts, crunch_list_suppliers and crunch_list_clients. List tools return compact summaries as {total, returned, items}; get tools return full records. List tools take search (case-insensitive substring match on any text or number in an item), fields (keep only these fields in each item; dot paths like supplier.companyName with raw: true) and limit. On paged lists (page, size, all) they apply to what was fetched: one page, or every page with all=true. Use them to fetch only what you need. Write tools are enabled: confirm amounts, dates and VAT treatment with the user before creating or changing records, and before issuing an invoice (issued invoices are final). Tools that change things take dry_run: true to preview the request without sending it; use it to show the user what will change.
Capabilities
Features and capabilities supported by this server
Protocol revision2025-11-25
| Capability | Details |
|---|---|
| tools | {
"listChanged": true
} |
| logging | {} |
| prompts | {
"listChanged": true
} |
Tools
Functions exposed to the LLM to take actions
| Name | Description |
|---|---|
| crunch_add_expense_attachmentB | Attach one or more files (receipts, invoices) to an existing expense. Existing attachments are kept. |
| crunch_add_expense_paymentA | Record that an expense was paid (fully or partly): date, amount, payment method and the bank account, credit card or director it was paid from. Existing payments are kept. |
| crunch_add_invoice_attachmentA | Attach files (for example timesheets) to a sales invoice. Existing attachments are kept; an invoice can have up to 5. |
| crunch_add_invoice_paymentA | Record a payment received from a customer against an issued invoice (full or part payment). This records the payment but doesn't reconcile the matching bank statement entry. Existing payments are kept. |
| crunch_archive_bank_accountA | Archive a bank account you no longer use (it stays in your records but is hidden), or restore an archived one with archive=false. |
| crunch_archive_credit_cardA | Archive a credit card you no longer use, or restore an archived one with archive=false. |
| crunch_auth_completeA | Finish a login started with crunch_auth_start by exchanging the authorisation code for tokens, which are saved to the token file. Pass the full URL the browser was redirected to, or just the code together with the state crunch_auth_start returned. |
| crunch_auth_startA | Start logging this server in to a Crunch account (OAuth 2.0 with PKCE). Returns a URL for the user to open and approve. After they click Allow, the browser is sent to the redirect URI; if nothing is listening there the page fails to load, which is fine: ask the user to copy the full URL from the address bar and pass it to crunch_auth_complete. Logging in replaces the current tokens, possibly with a different Crunch account. |
| crunch_auth_statusA | Show whether this server is logged in to Crunch: where the tokens come from, the granted scopes, when the access token expires and whether a refresh token is available. Never shows the tokens themselves. |
| crunch_create_bank_accountB | Add a bank account to Crunch so payments can be recorded against it. |
| crunch_create_clientA | Create a client (customer) to invoice. A name and a billing address with line1, line2 and country are needed. Check crunch_list_clients first to avoid duplicates. |
| crunch_create_credit_cardA | Add a credit card to Crunch so expenses can be paid from it. Set its opening balance with crunch_set_credit_card_opening_balance. |
| crunch_create_expenseA | Record an expense: who it was from, the date, one or more lines (expense type, VAT type, gross amount), and optionally how it was paid and the receipt. Look up valid values first: crunch_list_expense_types, crunch_list_vat_types, crunch_list_payment_methods, crunch_list_bank_accounts. The date must be in an open accounting period. Refuses an expense that matches an existing one (same supplier, date, gross amount and supplier reference) unless allow_duplicate=true. |
| crunch_create_invoiceA | Create a draft sales invoice for a client: date, lines (description, unit price excluding VAT, quantity, VAT rate), payment terms and the bank account to be paid into. Crunch's API only supports GBP. The invoice stays a draft until crunch_issue_invoice. Look up the client (crunch_list_clients), VAT rates (crunch_list_vat_types for=invoices) and bank account first. |
| crunch_create_recurring_expenseA | Set up a recurring expense: a template expense (supplier, lines, optional payment method) that Crunch creates automatically on a schedule. Schedule values are Crunch's own; look at an existing one with crunch_get_recurring_expense if you're unsure of the names. |
| crunch_create_supplierA | Create a supplier. Only company_name is required; a default expense_type makes new expenses for this supplier quicker. Check crunch_list_suppliers first to avoid duplicates. |
| crunch_download_expense_attachmentA | Download a receipt or other file attached to an expense. Images are returned so you can read them; other files (PDFs) come back as an embedded resource. Attachment IDs and names come from crunch_get_expense. |
| crunch_download_invoice_attachmentA | Download a file attached to a sales invoice. Attachment IDs and names come from crunch_get_invoice. |
| crunch_download_invoice_pdfA | Download a sales invoice as a PDF, as Crunch renders it for the customer. Returned as an embedded resource; use save_to to also write it to disk (when the server sets CRUNCH_FILES_DIR). |
| crunch_get_aged_creditorsA | What the business owes suppliers and for how long: the outstanding balance of every unpaid or part-paid expense, grouped by age (0-30, 31-60, 61-90 and over 90 days since the expense date, since Crunch's expenses have no due date) and by supplier, largest first. Reads every expense up to the report date, so it can take a few seconds on a large account. details=true also lists each expense. |
| crunch_get_aged_debtorsA | Who owes the business money and for how long: the outstanding balance of every issued sales invoice, grouped by days past its due date (current, 1-30, 31-60, 61-90 and over 90 days) and by customer, largest first. Drafts are left out. Reads every invoice, so it can take a few seconds on a large account. details=true also lists each invoice. |
| crunch_get_bank_accountA | Get one bank account in full: balance, account details, bank feed, unmatched statement entries and whether it can be edited, archived or deleted. |
| crunch_get_clientA | Get a client (customer) in full: contact details, billing address, payment terms and note. |
| crunch_get_company_detailsB | Get the business's details from Crunch: company name and number, VAT registration number, current VAT scheme (for example flat rate, with industry and limited cost trader status), and business and registered addresses. |
| crunch_get_credit_cardA | Get one credit card in full, including its opening balance. |
| crunch_get_default_invoice_noteA | Get the default note Crunch prints on new sales invoices (often payment instructions). |
| crunch_get_expenseA | Get one expense: its lines (types, VAT, amounts), payments, attachments, credit notes, and whether it can still be edited or deleted. raw=true returns the API object. |
| crunch_get_expenses_totalA | Total the expenses matching the filters (gross amount, plus under- and over-paid amounts) without listing them. Handy for "how much did I spend on travel this year?". |
| crunch_get_invoiceA | Get one sales invoice: customer, dates, lines, VAT, payments received, credit notes, attachments and status. raw=true returns the API object. |
| crunch_get_invoice_statusA | Get an invoice's current state (status, number, amounts, outstanding balance, due date), which is lighter than crunch_get_invoice. |
| crunch_get_invoice_totalsA | Get sales invoice totals: with no filters, everything invoiced and still outstanding; with filters (client, status, issue or due dates, invoice number, recurring), the amount invoiced, owed to you and owed by you for the matching invoices. |
| crunch_get_opening_balancesB | Get the opening balances of bank accounts or credit cards, and whether each can still be edited. |
| crunch_get_overviewA | A one-call snapshot of the business: company and VAT details, bank account and credit card balances, sales invoice totals (invoiced and outstanding) and open accounting periods. A good first call for questions like "how is my business doing?". |
| crunch_get_recurring_expenseA | Get a recurring expense in full: the template expense (supplier, lines, payment) and its schedule (recurringEvent). |
| crunch_get_supplierC | Get a supplier in full. |
| crunch_get_user_detailsA | Get the logged-in Crunch user: ID, email address, first and last name. |
| crunch_get_vat_summaryA | Net, VAT and gross by VAT type for a period, for sales (issued invoices by issue date) and purchases (expenses by expense date), with VAT on sales minus VAT on purchases. Use it to sense-check a VAT return; it is not one (Crunch's API has no VAT returns, and the Flat Rate Scheme and cash accounting work VAT out differently). Reads each invoice in the period, so long periods take a while. |
| crunch_issue_invoiceA | Issue a draft sales invoice: it gets its invoice number and is posted to your accounts. This is final (correct mistakes afterwards with a credit note in Crunch). It does not email the customer; see crunch_email_invoice. |
| crunch_list_accounting_periodsA | List the open accounting periods (financial years) with their start and end dates and status. Expenses can only be created or changed in an open period; closed years can't be edited. |
| crunch_list_bank_account_paymentsA | List payments recorded in Crunch against a bank account (supplier payments, customer payments, transfers, salaries, dividends, tax payments...), either reconciled with the bank statement or still unreconciled. Paged; newest first by default. |
| crunch_list_bank_accountsA | List the business's bank accounts with their current balance, sort code and account number, default flag, bank feed state and how many statement entries still need matching. Use the IDs when recording payments. |
| crunch_list_clientsA | List the business's clients (the customers you invoice) with email, payment terms and billing address. Use the IDs as the customer on invoices. |
| crunch_list_countriesA | List the countries Crunch knows, with the country codes to use in addresses and supplier records, and whether each is an EU member. |
| crunch_list_credit_cardsA | List the business's credit cards with their balances, default flag and unmatched statement entries. |
| crunch_list_credit_notesA | List credit notes: those issued against your sales invoices (for=invoices, the default), those from suppliers against expenses (for=expenses), or both (for=all), newest first, with the invoice or expense they belong to, amount, state and refunds. Crunch's public API can't create credit notes; do that in the Crunch app. Reads the invoices that have credits one by one, so it can take a few seconds. |
| crunch_list_expense_typesA | List the expense types (categories) Crunch accepts in expenseType fields, for example ACCOUNTANCY, TELEPHONE or TRAVEL_AND_SUBSISTENCE, grouped as in Crunch, with each type's default VAT type. Use the |
| crunch_list_expensesA | List expenses (purchases, receipts and bills), newest first, filtered by supplier, expense type, date, payment date, payment method or whether a receipt is attached. Each result shows supplier, amounts, status, outstanding balance and payment method. Paged (up to 200 per page); use all=true to fetch every page. |
| crunch_list_invoicesA | List sales invoices, newest first: number, customer, dates, status, amounts and outstanding balance. Filter by client, or by status (which fetches every page and filters here). Paged (up to 200 per page); use all=true to fetch every page. |
| crunch_list_payment_methodsA | List payment methods (for example EFT, CASH, DIRECTORS_EXPENSES) for recording expense payments or invoice payments. Use |
| crunch_list_personsA | List the people (directors and employees) linked to the business on a date. Use their IDs as the person for DIRECTORS_EXPENSES payments and as the employee on expense lines. |
| crunch_list_recurring_expensesA | List recurring expenses (regular bills such as rent, phone or software subscriptions that Crunch creates automatically) with supplier, amount, status and next date. |
| crunch_list_suppliersA | List suppliers (who you buy from), with their default expense type, country and VAT number. |
| crunch_list_vat_typesA | List the VAT types (rates) Crunch accepts, with their percentages. Expenses and invoices have separate lists; use the names exactly as shown (for example "Standard", "Exempt", "Outside the Scope"), not code-style values. |
| crunch_set_credit_card_opening_balanceA | Set a credit card's opening balance (the amount owed when you started using Crunch for it). Creates it, or updates an existing editable one. |
| crunch_set_default_bank_accountA | Make a bank account the default one, used for new invoices and payments. |
| crunch_set_default_credit_cardC | Make a credit card the default one. |
| crunch_update_bank_accountA | Change a bank account's details. Only the fields you pass change; the rest are kept. Sort code and account number can't be changed once the account has a bank feed or reconciled entries. |
| crunch_update_clientA | Change a client's details. Only the fields you pass change; the rest are kept (a new billing_address replaces the whole address). |
| crunch_update_credit_cardB | Change a credit card's details. Only the fields you pass change. |
| crunch_update_expenseA | Change an expense. The current expense is fetched and only what you pass changes: posting_date, supplier, reference, note, or line_items (which replace all lines). Payments and attachments are kept as they are; use crunch_add_expense_payment, crunch_remove_expense_payment and crunch_add_expense_attachment for those. Reconciled expenses and closed years can't be changed. |
| crunch_update_invoiceA | Change a sales invoice. The current invoice is fetched and only what you pass changes; existing payments and attachments are kept. |
| crunch_update_recurring_expenseA | Change a recurring expense: its lines, its schedule (for example pause it with enabled=false, or change the next or end date), or any field via |
| crunch_update_supplierA | Change a supplier's details, or archive/restore it. Only the fields you pass change. |
Prompts
Interactive templates invoked by user choice
| Name | Description |
|---|---|
| business_health_check | A plain-English review of the business: cash in the bank, money owed to and by you, overdue invoices, unpaid bills and anything that needs attention. |
| chase_overdue_invoices | Find overdue sales invoices and draft polite chasing emails for each customer. |
| create_invoice | Raise a sales invoice for a client, checking the client, VAT rate, payment terms and bank account. |
| expense_review | Review a period's expenses for missing receipts, unpaid bills, odd categories and possible duplicates. |
| period_summary | Income, spending and cash summary for a month, quarter or year, for example to prepare for a VAT return or year end. |
| record_receipt | Turn a receipt, bill or description of a purchase into a correctly categorised Crunch expense. |
Resources
Contextual data attached and managed by the client
| Name | Description |
|---|---|
No resources | |
TDQS
Scored across 63 tools
Most tools target a clearly distinct resource and action, and descriptions help separate subtle pairs such as get_invoice/get_invoice_status/get_invoice_totals and list_expenses/get_expenses_total. Some reporting and totals tools overlap, and the large surface raises misselection risk, but not severely.
Nearly all tools follow a predictable crunch_verb_noun snake_case pattern, such as crunch_list_clients, crunch_create_invoice and crunch_update_expense. The auth trio (crunch_auth_start/status/complete) uses noun_verb instead, which is a minor deviation.
At 63 tools, the server is far above the typical 3-15 range and presents a heavy tool-selection surface. The breadth is partly justified by accounting CRUD across clients, suppliers, invoices, expenses, banks, cards, recurring items and reports, but it is still excessive.
Core accounting workflows—clients, suppliers, invoices, expenses, payments, attachments, bank and credit-card management, and key reports—are well covered. However, crunch_issue_invoice references a missing crunch_email_invoice tool, and there is no reconciliation operation or delete path for some resources, leaving minor dead ends.