Tool reference

crunch-mcp has 70 tools in 9 toolsets: 36 read, 24 write, 9 delete and 1 email. It also has 6 prompts.

Each tool is labelled with the setting it needs:

Label	Registered when
🟢 read	Always
🟠 write	CRUNCH_ALLOW_WRITES=true
🔴 delete	CRUNCH_ALLOW_WRITES=true and CRUNCH_ALLOW_DELETES=true
🟣 email	CRUNCH_ALLOW_WRITES=true and CRUNCH_ALLOW_EMAIL=true

Every tool also needs its toolset to be enabled in CRUNCH_TOOLSETS, which enables all toolsets by default. List tools return compact summaries and take raw: true for the full API objects. Amounts can be given as numbers (120) or decimal strings ("120.00"), and dates as YYYY-MM-DD.

Contents

• account: Login status and the OAuth login flow, the logged-in user, company details (VAT number and scheme, addresses) and a one-call business overview.
• reference: Lookups for the values Crunch expects: expense types, VAT types, payment methods, countries, open accounting periods, and directors and employees.
• banking: Bank accounts and credit cards: balances, details, payments recorded against them, opening balances, default accounts, archiving.
• clients: Clients (the customers you invoice): list, look up, create, update and delete.
• suppliers: Suppliers (who you buy from): list, look up, create, update, archive and delete.
• expenses: Expenses: list and filter, totals, create with lines, payments and receipts, update, record and remove payments, attach and download receipts, delete.
• recurring: Recurring expenses that Crunch creates on a schedule: list, create, pause or change, delete.
• invoices: Sales invoices: list and filter, totals, create drafts, update, issue, email to the customer, record and remove payments, attachments, PDF download, delete.
• raw: A raw API escape hatch for anything the other tools don’t cover. It is limited to GET requests unless writes are enabled.

account

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

Tool	Access	Summary
crunch_auth_complete	🟢 read	Finish Crunch login
crunch_auth_start	🟢 read	Start Crunch login
crunch_auth_status	🟢 read	Crunch login status
crunch_get_company_details	🟢 read	Get company details
crunch_get_overview	🟢 read	Business overview
crunch_get_user_details	🟢 read	Get user details

crunch_auth_complete

🟢 read

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).

Argument	Type	Required	Description
redirected_url	string	yes	The full URL from the browser’s address bar after clicking Allow (it contains code= and state=), or just the code

crunch_auth_start

🟢 read

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.

No arguments.

crunch_auth_status

🟢 read

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.

No arguments.

crunch_get_company_details

🟢 read

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.

Argument	Type	Required	Description
raw	boolean		Return the full objects from the API instead of compact summaries (larger)

crunch_get_overview

🟢 read

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?”.

No arguments.

crunch_get_user_details

🟢 read

Get the logged-in Crunch user: ID, email address, first and last name.

No arguments.

reference

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

Tool	Access	Summary
crunch_list_accounting_periods	🟢 read	List open accounting periods
crunch_list_countries	🟢 read	List countries
crunch_list_expense_types	🟢 read	List expense types
crunch_list_payment_methods	🟢 read	List payment methods
crunch_list_persons	🟢 read	List directors and employees
crunch_list_vat_types	🟢 read	List VAT types

crunch_list_accounting_periods

🟢 read

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.

No arguments.

crunch_list_countries

🟢 read

List the countries Crunch knows, with the country codes to use in addresses and supplier records, and whether each is an EU member.

Argument	Type	Required	Description
search	string		Case-insensitive substring filter

crunch_list_expense_types

🟢 read

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 name values when creating expenses and suppliers.

Argument	Type	Required	Description
date	string		Types valid on this date (YYYY-MM-DD; default today)
include_deprecated	boolean		Include deprecated types (default false)
raw	boolean		Return the API response unchanged
search	string		Case-insensitive substring filter on names and groups

crunch_list_payment_methods

🟢 read

List payment methods (for example EFT, CASH, DIRECTORS_EXPENSES) for recording expense payments or invoice payments. Use name as the payment method.

Argument	Type	Required	Description
direction	string		For invoices: the payment direction as Crunch names it (default INCOMING, money received from customers)
for	"expenses" | "invoices"		Expense payments (default) or invoice (customer) payments

crunch_list_persons

🟢 read

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.

Argument	Type	Required	Description
date	string		Date the people were in post (YYYY-MM-DD; default today)
role	string		Only people with this role, as Crunch names it (for example DIRECTOR)

crunch_list_vat_types

🟢 read

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.

Argument	Type	Required	Description
for	"expenses" | "invoices" | "both"		Which list: expenses, invoices or both (default both)

banking

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

Tool	Access	Summary
crunch_archive_bank_account	🟠 write	Archive or restore bank account
crunch_archive_credit_card	🟠 write	Archive or restore credit card
crunch_create_bank_account	🟠 write	Create bank account
crunch_create_credit_card	🟠 write	Create credit card
crunch_delete_bank_account	🔴 delete	Delete bank account
crunch_delete_credit_card	🔴 delete	Delete credit card
crunch_get_bank_account	🟢 read	Get bank account
crunch_get_credit_card	🟢 read	Get credit card
crunch_get_opening_balances	🟢 read	Get opening balances
crunch_list_bank_account_payments	🟢 read	List bank account payments
crunch_list_bank_accounts	🟢 read	List bank accounts
crunch_list_credit_cards	🟢 read	List credit cards
crunch_set_credit_card_opening_balance	🟠 write	Set credit card opening balance
crunch_set_default_bank_account	🟠 write	Set default bank account
crunch_set_default_credit_card	🟠 write	Set default credit card
crunch_update_bank_account	🟠 write	Update bank account
crunch_update_credit_card	🟠 write	Update credit card

crunch_archive_bank_account

🟠 write

Archive a bank account you no longer use (it stays in your records but is hidden), or restore an archived one with archive=false.

Argument	Type	Required	Description
bank_account_id	integer	yes	Bank account ID (see crunch_list_bank_accounts)
archive	boolean		true to archive (default), false to restore

crunch_archive_credit_card

🟠 write

Archive a credit card you no longer use, or restore an archived one with archive=false.

Argument	Type	Required	Description
credit_card_id	integer	yes	Credit card ID (see crunch_list_credit_cards)
archive	boolean		true to archive (default), false to restore

crunch_create_bank_account

🟠 write

Add a bank account to Crunch so payments can be recorded against it.

Argument	Type	Required	Description
bank_name	string	yes	Bank, for example Starling
display_name	string	yes	Name shown in Crunch, for example Business Current Account
account_name	string		Name on the account
account_number	string		Account number
bic	string		BIC
extra	object		Additional raw fields for the request body, using Crunch’s own field names (advanced). Merged last.
iban	string		IBAN
personal	boolean		A personal (not business) account used for business payments
sort_code	string		Sort code, for example 12-34-56

crunch_create_credit_card

🟠 write

Add a credit card to Crunch so expenses can be paid from it. Set its opening balance with crunch_set_credit_card_opening_balance.

Argument	Type	Required	Description
display_name	string	yes	Name shown in Crunch, for example Amex Business
card_number	string		Card number (Crunch usually only needs the last four digits)
extra	object		Additional raw fields for the request body, using Crunch’s own field names (advanced). Merged last.
personal	boolean		A personal card used for business payments

crunch_delete_bank_account

🔴 delete · destructive

Permanently delete a bank account. Only possible when nothing is recorded against it (see deletable in crunch_get_bank_account); archive it otherwise.

Argument	Type	Required	Description
bank_account_id	integer	yes	Bank account ID (see crunch_list_bank_accounts)

crunch_delete_credit_card

🔴 delete · destructive

Permanently delete a credit card. Only possible when nothing is recorded against it; archive it otherwise.

Argument	Type	Required	Description
credit_card_id	integer	yes	Credit card ID (see crunch_list_credit_cards)

crunch_get_bank_account

🟢 read

Get one bank account in full: balance, account details, bank feed, unmatched statement entries and whether it can be edited, archived or deleted.

Argument	Type	Required	Description
bank_account_id	integer	yes	Bank account ID (see crunch_list_bank_accounts)

crunch_get_credit_card

🟢 read

Get one credit card in full, including its opening balance.

Argument	Type	Required	Description
credit_card_id	integer	yes	Credit card ID (see crunch_list_credit_cards)

crunch_get_opening_balances

🟢 read

Get the opening balances of bank accounts or credit cards, and whether each can still be edited.

Argument	Type	Required	Description
account_ids	integer[]	yes	Bank account or credit card IDs
type	"bank_accounts" | "credit_cards"		Account type: bank_accounts (default) or credit_cards

crunch_list_bank_account_payments

🟢 read

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.

Argument	Type	Required	Description
bank_account_id	integer	yes	Bank account ID (see crunch_list_bank_accounts)
reconciled	boolean	yes	true for payments matched to bank statement entries, false for those still waiting to be reconciled
all	boolean		Fetch every page (up to max_items) instead of a single page
max_items	integer		With all=true, stop after this many results (default 1000)
page	integer		Page to fetch, starting at 0 (default 0)
raw	boolean		Return the full objects from the API instead of compact summaries (larger)
size	integer		Results per page, up to 200 (default 50)
sort	string		Sort order as field,asc or field,desc, for example postingDate,desc

crunch_list_bank_accounts

🟢 read

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.

Argument	Type	Required	Description
raw	boolean		Return the full objects from the API instead of compact summaries (larger)
search	string		Case-insensitive substring filter on names and numbers
status	"active" | "archived" | "all"		Which to list: active (default), archived or all

crunch_list_credit_cards

🟢 read

List the business’s credit cards with their balances, default flag and unmatched statement entries.

Argument	Type	Required	Description
raw	boolean		Return the full objects from the API instead of compact summaries (larger)
search	string		Case-insensitive substring filter on names and numbers
status	"active" | "archived" | "all"		Which to list: active (default), archived or all

crunch_set_credit_card_opening_balance

🟠 write

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.

Argument	Type	Required	Description
credit_card_id	integer	yes	Credit card ID (see crunch_list_credit_cards)
opening_balance	number | string	yes	Opening balance, for example 250.00

crunch_set_default_bank_account

🟠 write

Make a bank account the default one, used for new invoices and payments.

Argument	Type	Required	Description
bank_account_id	integer	yes	Bank account ID (see crunch_list_bank_accounts)

crunch_set_default_credit_card

🟠 write

Make a credit card the default one.

Argument	Type	Required	Description
credit_card_id	integer	yes	Credit card ID (see crunch_list_credit_cards)

crunch_update_bank_account

🟠 write

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.

Argument	Type	Required	Description
bank_account_id	integer	yes	Bank account ID (see crunch_list_bank_accounts)
account_name	string		Name on the account
account_number	string		Account number
bank_name	string		Bank, for example Starling
bic	string		BIC
display_name	string		Name shown in Crunch, for example Business Current Account
extra	object		Additional raw fields for the request body, using Crunch’s own field names (advanced). Merged last.
iban	string		IBAN
personal	boolean		A personal (not business) account used for business payments
sort_code	string		Sort code, for example 12-34-56

crunch_update_credit_card

🟠 write

Change a credit card’s details. Only the fields you pass change.

Argument	Type	Required	Description
credit_card_id	integer	yes	Credit card ID (see crunch_list_credit_cards)
card_number	string		Card number (Crunch usually only needs the last four digits)
display_name	string		Name shown in Crunch, for example Amex Business
extra	object		Additional raw fields for the request body, using Crunch’s own field names (advanced). Merged last.
personal	boolean		A personal card used for business payments

clients

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

Tool	Access	Summary
crunch_create_client	🟠 write	Create client
crunch_delete_client	🔴 delete	Delete client
crunch_get_client	🟢 read	Get client
crunch_list_clients	🟢 read	List clients
crunch_update_client	🟠 write	Update client

crunch_create_client

🟠 write

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.

Argument	Type	Required	Description
billing_address	object	yes	Billing address
billing_address.country	string	yes	Country code, for example GB (see crunch_list_countries)
billing_address.line1	string	yes	First line of the address
billing_address.line2	string	yes	Second line (the town or city if the address is short); Crunch requires it
billing_address.line3	string		Third line
billing_address.line4	string		Fourth line
billing_address.post_code	string		Postcode
name	string	yes	Customer name, for example Example Customer Ltd
email	string		Email address invoices are sent to
extra	object		Additional raw fields for the request body, using Crunch’s own field names (advanced). Merged last.
note	string		Internal note about the customer
payment_terms_days	integer		Default payment terms in days, for example 30

crunch_delete_client

🔴 delete · destructive

Delete a client (customer). Crunch refuses if the client has invoices.

Argument	Type	Required	Description
client_id	integer	yes	Client (customer) ID (see crunch_list_clients)

crunch_get_client

🟢 read

Get a client (customer) in full: contact details, billing address, payment terms and note.

Argument	Type	Required	Description
client_id	integer	yes	Client (customer) ID (see crunch_list_clients)

crunch_list_clients

🟢 read

List the business’s clients (the customers you invoice) with email, payment terms and billing address. Use the IDs as the customer on invoices.

Argument	Type	Required	Description
limit	integer		Maximum number of results
raw	boolean		Return the full objects from the API instead of compact summaries (larger)
search	string		Case-insensitive substring filter on name, email and postcode

crunch_update_client

🟠 write

Change a client’s details. Only the fields you pass change; the rest are kept (a new billing_address replaces the whole address).

Argument	Type	Required	Description
client_id	integer	yes	Client (customer) ID (see crunch_list_clients)
billing_address	object		New billing address (replaces the whole address)
billing_address.country	string	yes	Country code, for example GB (see crunch_list_countries)
billing_address.line1	string	yes	First line of the address
billing_address.line2	string	yes	Second line (the town or city if the address is short); Crunch requires it
billing_address.line3	string		Third line
billing_address.line4	string		Fourth line
billing_address.post_code	string		Postcode
email	string		Email address invoices are sent to
extra	object		Additional raw fields for the request body, using Crunch’s own field names (advanced). Merged last.
name	string		New name
note	string		Internal note about the customer
payment_terms_days	integer		Default payment terms in days, for example 30

suppliers

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

Tool	Access	Summary
crunch_create_supplier	🟠 write	Create supplier
crunch_delete_supplier	🔴 delete	Delete supplier
crunch_get_supplier	🟢 read	Get supplier
crunch_list_suppliers	🟢 read	List suppliers
crunch_update_supplier	🟠 write	Update supplier

crunch_create_supplier

🟠 write

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.

Argument	Type	Required	Description
company_name	string	yes	Supplier name, for example Example Supplier Ltd
contact_name	string		Contact at the supplier
country	string		Country code, for example GB (see crunch_list_countries)
expense_type	string		Default expense type for this supplier’s expenses, for example TELEPHONE (see crunch_list_expense_types)
extra	object		Additional raw fields for the request body, using Crunch’s own field names (advanced). Merged last.
vat_registration_number	string		The supplier’s VAT number

crunch_delete_supplier

🔴 delete · destructive

Delete a supplier. Only possible when it has no expenses (see deletable); archive it with crunch_update_supplier otherwise.

Argument	Type	Required	Description
supplier_id	integer	yes	Supplier ID (see crunch_list_suppliers)

crunch_get_supplier

🟢 read

Get a supplier in full.

Argument	Type	Required	Description
supplier_id	integer	yes	Supplier ID (see crunch_list_suppliers)

crunch_list_suppliers

🟢 read

List suppliers (who you buy from), with their default expense type, country and VAT number. search matches part of a name; name asks Crunch for an exact company name. Use the IDs when creating expenses.

Argument	Type	Required	Description
include_archived	boolean		Include archived suppliers (default false)
limit	integer		Maximum number of results
name	string		Exact company name to look up
raw	boolean		Return the full objects from the API instead of compact summaries (larger)
search	string		Case-insensitive substring filter on name, contact and VAT number

crunch_update_supplier

🟠 write

Change a supplier’s details, or archive/restore it. Only the fields you pass change.

Argument	Type	Required	Description
supplier_id	integer	yes	Supplier ID (see crunch_list_suppliers)
archived	boolean		Archive (true) or restore (false) the supplier
company_name	string		New name
contact_name	string		Contact at the supplier
country	string		Country code, for example GB (see crunch_list_countries)
expense_type	string		Default expense type for this supplier’s expenses, for example TELEPHONE (see crunch_list_expense_types)
extra	object		Additional raw fields for the request body, using Crunch’s own field names (advanced). Merged last.
vat_registration_number	string		The supplier’s VAT number

expenses

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

Tool	Access	Summary
crunch_add_expense_attachment	🟠 write	Attach receipt to expense
crunch_add_expense_payment	🟠 write	Record expense payment
crunch_create_expense	🟠 write	Create expense
crunch_delete_expense	🔴 delete	Delete expense
crunch_download_expense_attachment	🟢 read	Download expense attachment
crunch_get_expense	🟢 read	Get expense
crunch_get_expenses_total	🟢 read	Get expenses total
crunch_list_expenses	🟢 read	List expenses
crunch_remove_expense_payment	🔴 delete	Remove expense payment
crunch_update_expense	🟠 write	Update expense

crunch_add_expense_attachment

🟠 write

Attach one or more files (receipts, invoices) to an existing expense. Existing attachments are kept.

Argument	Type	Required	Description
attachments	object[]	yes	Files to attach
attachments[].file_name	string	yes	File name including its extension, for example receipt.jpg
attachments[].content_base64	string		The file as base64, or as a data URI (data:image/jpeg;base64,…)
attachments[].file_path	string		Instead of content_base64: path to the file on the machine running this server
attachments[].mime_type	string		MIME type, for example image/jpeg (guessed from the file name when omitted)
expense_id	integer	yes	Expense ID (see crunch_list_expenses)

crunch_add_expense_payment

🟠 write

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.

Argument	Type	Required	Description
amount	number | string	yes	Amount paid, for example 120.00
date	string	yes	Payment date (YYYY-MM-DD)
expense_id	integer	yes	Expense ID (see crunch_list_expenses)
bank_account_id	integer		Bank account the payment went through (see crunch_list_bank_accounts)
credit_card_id	integer		Credit card the payment was made with (see crunch_list_credit_cards)
payment_method	string		Payment method name, for example EFT, CASH or DIRECTORS_EXPENSES (default EFT; see crunch_list_payment_methods)
person_id	integer		For DIRECTORS_EXPENSES: the director who paid (see crunch_list_persons)

crunch_create_expense

🟠 write

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.

Argument	Type	Required	Description
line_items	object[]	yes	One or more lines, each with its own expense type, VAT type and amount
line_items[].expense_type	string	yes	Expense type name, for example ACCOUNTANCY or TELEPHONE (see crunch_list_expense_types)
line_items[].gross_amount	number | string	yes	Total including VAT, for example 120.00
line_items[].description	string		What was bought
line_items[].employee_id	integer		Director or employee the line relates to (see crunch_list_persons)
line_items[].net_amount	number | string		Amount before VAT (normally worked out by Crunch from the VAT type)
line_items[].vat_amount	number | string		VAT amount (normally worked out by Crunch from the VAT type)
line_items[].vat_type	string		VAT type display name, for example Standard, Exempt or Outside the Scope (see crunch_list_vat_types). Defaults to the expense type’s default VAT type.
posting_date	string	yes	Date of the expense or receipt (YYYY-MM-DD); must be in an open accounting period
attachments	object[]		Receipts or invoices to attach
attachments[].file_name	string	yes	File name including its extension, for example receipt.jpg
attachments[].content_base64	string		The file as base64, or as a data URI (data:image/jpeg;base64,…)
attachments[].file_path	string		Instead of content_base64: path to the file on the machine running this server
attachments[].mime_type	string		MIME type, for example image/jpeg (guessed from the file name when omitted)
create_supplier	boolean		With supplier_name: create the supplier if it doesn’t exist yet (default false)
extra	object		Additional raw ExpenseDto fields, using Crunch’s own field names (advanced). Merged last.
note	string		Internal note
payments	object[]		How it was paid; leave out to record it as unpaid
payments[].amount	number | string	yes	Amount paid, for example 120.00
payments[].date	string	yes	Payment date (YYYY-MM-DD)
payments[].bank_account_id	integer		Bank account the payment went through (see crunch_list_bank_accounts)
payments[].credit_card_id	integer		Credit card the payment was made with (see crunch_list_credit_cards)
payments[].payment_method	string		Payment method name, for example EFT, CASH or DIRECTORS_EXPENSES (default EFT; see crunch_list_payment_methods)
payments[].person_id	integer		For DIRECTORS_EXPENSES: the director who paid (see crunch_list_persons)
supplier_id	integer		Supplier ID (see crunch_list_suppliers). Give this or supplier_name.
supplier_name	string		Instead of supplier_id: the supplier’s exact name
supplier_reference	string		The supplier’s invoice or receipt number

crunch_delete_expense

🔴 delete · destructive

Permanently delete an expense with its lines, payments and attachments. Not possible for reconciled expenses or those in a closed year.

Argument	Type	Required	Description
expense_id	integer	yes	Expense ID (see crunch_list_expenses)

crunch_download_expense_attachment

🟢 read

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.

Argument	Type	Required	Description
attachment_id	integer	yes	Attachment ID within the expense (0, 1, 2…; see crunch_get_expense)
expense_id	integer	yes	Expense ID (see crunch_list_expenses)
file_name	string		Attachment file name (looked up when omitted)
save_to	string		Also save the file on the machine running this server: a directory (the file keeps its name) or a full path. Existing files are never overwritten.

crunch_get_expense

🟢 read

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.

Argument	Type	Required	Description
expense_id	integer	yes	Expense ID (see crunch_list_expenses)
raw	boolean		Return the API object unchanged (the base for hand-made updates)

crunch_get_expenses_total

🟢 read

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?”.

Argument	Type	Required	Description
status	string	yes	Expense status to total, as Crunch names it in the status field of expenses (see crunch_list_expenses)
end_date	string		Expenses dated on or before (YYYY-MM-DD)
expense_type	string		Only this expense type, for example TRAVEL_AND_SUBSISTENCE
has_attachment	boolean		Only expenses with (true) or without (false) a receipt attached
payment_end_date	string		Paid on or before (YYYY-MM-DD)
payment_method	string		Only expenses paid this way, for example EFT
payment_start_date	string		Paid on or after (YYYY-MM-DD)
start_date	string		Expenses dated on or after (YYYY-MM-DD)
supplier_id	integer		Only this supplier’s expenses

crunch_list_expenses

🟢 read

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.

Argument	Type	Required	Description
all	boolean		Fetch every page (up to max_items) instead of a single page
end_date	string		Expenses dated on or before (YYYY-MM-DD)
expense_type	string		Only this expense type, for example TRAVEL_AND_SUBSISTENCE
has_attachment	boolean		Only expenses with (true) or without (false) a receipt attached
max_items	integer		With all=true, stop after this many results (default 1000)
page	integer		Page to fetch, starting at 0 (default 0)
payment_end_date	string		Paid on or before (YYYY-MM-DD)
payment_method	string		Only expenses paid this way, for example EFT
payment_start_date	string		Paid on or after (YYYY-MM-DD)
raw	boolean		Return the full objects from the API instead of compact summaries (larger)
size	integer		Results per page, up to 200 (default 50)
sort	string		Sort order as field,asc or field,desc, for example postingDate,desc
start_date	string		Expenses dated on or after (YYYY-MM-DD)
supplier_id	integer		Only this supplier’s expenses

crunch_remove_expense_payment

🔴 delete · destructive

Remove a payment from an expense, leaving the expense itself (it becomes unpaid or part-paid). Reconciled payments can’t be removed. See crunch_get_expense for payment IDs.

Argument	Type	Required	Description
expense_id	integer	yes	Expense ID (see crunch_list_expenses)
payment_id	integer		Payment to remove; omit to remove all of the expense’s payments

crunch_update_expense

🟠 write

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.

Argument	Type	Required	Description
expense_id	integer	yes	Expense ID (see crunch_list_expenses)
changes	object		Raw ExpenseDto fields to merge into the current expense (advanced)
line_items	object[]		Replacement lines (all existing lines are replaced)
line_items[].expense_type	string	yes	Expense type name, for example ACCOUNTANCY or TELEPHONE (see crunch_list_expense_types)
line_items[].gross_amount	number | string	yes	Total including VAT, for example 120.00
line_items[].description	string		What was bought
line_items[].employee_id	integer		Director or employee the line relates to (see crunch_list_persons)
line_items[].net_amount	number | string		Amount before VAT (normally worked out by Crunch from the VAT type)
line_items[].vat_amount	number | string		VAT amount (normally worked out by Crunch from the VAT type)
line_items[].vat_type	string		VAT type display name, for example Standard, Exempt or Outside the Scope (see crunch_list_vat_types). Defaults to the expense type’s default VAT type.
note	string		New internal note
posting_date	string		New date (YYYY-MM-DD)
supplier_id	integer		Move the expense to this supplier
supplier_reference	string		New supplier reference

recurring

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

Tool	Access	Summary
crunch_create_recurring_expense	🟠 write	Create recurring expense
crunch_delete_recurring_expense	🔴 delete	Delete recurring expense
crunch_get_recurring_expense	🟢 read	Get recurring expense
crunch_list_recurring_expenses	🟢 read	List recurring expenses
crunch_update_recurring_expense	🟠 write	Update recurring expense

crunch_create_recurring_expense

🟠 write

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.

Argument	Type	Required	Description
line_items	object[]	yes	One or more lines, each with its own expense type, VAT type and amount
line_items[].expense_type	string	yes	Expense type name, for example ACCOUNTANCY or TELEPHONE (see crunch_list_expense_types)
line_items[].gross_amount	number | string	yes	Total including VAT, for example 120.00
line_items[].description	string		What was bought
line_items[].employee_id	integer		Director or employee the line relates to (see crunch_list_persons)
line_items[].net_amount	number | string		Amount before VAT (normally worked out by Crunch from the VAT type)
line_items[].vat_amount	number | string		VAT amount (normally worked out by Crunch from the VAT type)
line_items[].vat_type	string		VAT type display name, for example Standard, Exempt or Outside the Scope (see crunch_list_vat_types). Defaults to the expense type’s default VAT type.
recurrence	object	yes	The schedule
recurrence.frequency	string	yes	How often, as Crunch names it in recurringEventFrequency (for example MONTHLY); check an existing recurring expense if unsure
recurrence.next_occurrence_date	string	yes	Date of the next (first) expense to create (YYYY-MM-DD)
recurrence.description	string		Description of the schedule
recurrence.enabled	boolean		Whether the schedule is active (default true)
recurrence.end_date	string		Last date, when it ends on a date (YYYY-MM-DD)
recurrence.end_type	string		How the schedule ends, as Crunch names it in recurringEventEndType (never, on a date, or after a number of occurrences)
recurrence.frequency_occurrence	string		Crunch’s frequencyOccurrence setting, if your schedule needs it
recurrence.occurrence_count	integer		Number of expenses to create, when it ends after a count
bank_account_id	integer		Bank account the payments come from
create_supplier	boolean		With supplier_name: create the supplier if it doesn’t exist yet (default false)
extra	object		Additional raw ExpenseDto fields, using Crunch’s own field names (advanced). Merged last.
note	string		Internal note
payment_method	string		Payment method for the created expenses, for example EFT
posting_date	string		Date on the template expense (defaults to the first occurrence)
supplier_id	integer		Supplier ID (see crunch_list_suppliers). Give this or supplier_name.
supplier_name	string		Instead of supplier_id: the supplier’s exact name
supplier_reference	string		The supplier’s invoice or receipt number

crunch_delete_recurring_expense

🔴 delete · destructive

Delete a recurring expense so no more expenses are created from it. Expenses it already created are kept. To pause it instead, use crunch_update_recurring_expense with enabled=false.

Argument	Type	Required	Description
recurring_expense_id	integer	yes	Recurring expense ID (see crunch_list_recurring_expenses)

crunch_get_recurring_expense

🟢 read

Get a recurring expense in full: the template expense (supplier, lines, payment) and its schedule (recurringEvent).

Argument	Type	Required	Description
recurring_expense_id	integer	yes	Recurring expense ID (see crunch_list_recurring_expenses)

crunch_list_recurring_expenses

🟢 read

List recurring expenses (regular bills such as rent, phone or software subscriptions that Crunch creates automatically) with supplier, amount, status and next date.

Argument	Type	Required	Description
all	boolean		Fetch every page (up to max_items) instead of a single page
max_items	integer		With all=true, stop after this many results (default 1000)
page	integer		Page to fetch, starting at 0 (default 0)
raw	boolean		Return the full objects from the API instead of compact summaries (larger)
size	integer		Results per page, up to 200 (default 50)
sort	string		Sort order as field,asc or field,desc, for example postingDate,desc

crunch_update_recurring_expense

🟠 write

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 changes. Only what you pass changes. Expenses already created aren’t affected.

Argument	Type	Required	Description
recurring_expense_id	integer	yes	Recurring expense ID (see crunch_list_recurring_expenses)
changes	object		Raw ExpenseDto fields to merge in, for example {“recurringEvent”: {“recurringEventFrequency”: “…”}} (advanced)
enabled	boolean		Pause (false) or resume (true) the schedule
end_date	string		New end date (YYYY-MM-DD)
line_items	object[]		Replacement lines (all existing lines are replaced)
line_items[].expense_type	string	yes	Expense type name, for example ACCOUNTANCY or TELEPHONE (see crunch_list_expense_types)
line_items[].gross_amount	number | string	yes	Total including VAT, for example 120.00
line_items[].description	string		What was bought
line_items[].employee_id	integer		Director or employee the line relates to (see crunch_list_persons)
line_items[].net_amount	number | string		Amount before VAT (normally worked out by Crunch from the VAT type)
line_items[].vat_amount	number | string		VAT amount (normally worked out by Crunch from the VAT type)
line_items[].vat_type	string		VAT type display name, for example Standard, Exempt or Outside the Scope (see crunch_list_vat_types). Defaults to the expense type’s default VAT type.
next_occurrence_date	string		New next date (YYYY-MM-DD)
note	string		New internal note
supplier_reference	string		New supplier reference

invoices

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

Tool	Access	Summary
crunch_add_invoice_attachment	🟠 write	Attach file to invoice
crunch_add_invoice_payment	🟠 write	Record invoice payment
crunch_create_invoice	🟠 write	Create invoice
crunch_delete_invoice	🔴 delete	Delete invoice
crunch_download_invoice_attachment	🟢 read	Download invoice attachment
crunch_download_invoice_pdf	🟢 read	Download invoice PDF
crunch_email_invoice	🟣 email	Email invoice to customer
crunch_get_default_invoice_note	🟢 read	Get default invoice note
crunch_get_invoice	🟢 read	Get invoice
crunch_get_invoice_status	🟢 read	Get invoice status
crunch_get_invoice_totals	🟢 read	Get invoice totals
crunch_issue_invoice	🟠 write	Issue invoice
crunch_list_invoices	🟢 read	List invoices
crunch_remove_invoice_payment	🔴 delete	Remove invoice payment
crunch_update_invoice	🟠 write	Update invoice

crunch_add_invoice_attachment

🟠 write

Attach files (for example timesheets) to a sales invoice. Existing attachments are kept; an invoice can have up to 5.

Argument	Type	Required	Description
attachments	object[]	yes	Files to attach (an invoice can have up to 5)
attachments[].file_name	string	yes	File name including its extension, for example receipt.jpg
attachments[].content_base64	string		The file as base64, or as a data URI (data:image/jpeg;base64,…)
attachments[].file_path	string		Instead of content_base64: path to the file on the machine running this server
attachments[].mime_type	string		MIME type, for example image/jpeg (guessed from the file name when omitted)
invoice_id	integer	yes	Invoice ID (see crunch_list_invoices)

crunch_add_invoice_payment

🟠 write

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.

Argument	Type	Required	Description
amount	number | string	yes	Amount received, for example 120.00
date	string	yes	Date the customer paid (YYYY-MM-DD)
invoice_id	integer	yes	Invoice ID (see crunch_list_invoices)
bank_account_id	integer		Bank account the money went into (defaults to the invoice’s bank account)
payment_method	string		Payment method name (default EFT; see crunch_list_payment_methods for=invoices)

crunch_create_invoice

🟠 write

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.

Argument	Type	Required	Description
client_id	integer	yes	Customer to invoice (see crunch_list_clients; create one with crunch_create_client)
issued_date	string	yes	Invoice date (YYYY-MM-DD)
items	object[]	yes	Invoice lines
items[].description	string	yes	What was sold, for example Consulting services
items[].price_excl_vat	number | string	yes	Unit price before VAT, for example 100.00
items[].vat_rate	string	yes	VAT type display name, for example Standard or Outside the Scope (see crunch_list_vat_types for=invoices)
items[].line_type	string		Crunch’s lineType (default S)
items[].quantity	number | string		Quantity (default 1)
attachments	object[]		Up to 5 files to attach
attachments[].file_name	string	yes	File name including its extension, for example receipt.jpg
attachments[].content_base64	string		The file as base64, or as a data URI (data:image/jpeg;base64,…)
attachments[].file_path	string		Instead of content_base64: path to the file on the machine running this server
attachments[].mime_type	string		MIME type, for example image/jpeg (guessed from the file name when omitted)
bank_account_id	integer		Bank account the customer should pay into, shown on the invoice (see crunch_list_bank_accounts)
due_date	string		Due date (YYYY-MM-DD); worked out from the payment terms when omitted
extra	object		Additional raw SalesInvoiceDto fields, using Crunch’s own field names (advanced). Merged last.
line_item_type	"SIMPLE" | "DETAILED"		SIMPLE (default) or DETAILED lines
note	string		Note printed on the invoice (see crunch_get_default_invoice_note)
payment_terms_days	integer		Payment terms in days, for example 28
purchase_order	string		The customer’s purchase order number
reference	string		Your reference
send_reminders	boolean		Have Crunch send payment reminders

crunch_delete_invoice

🔴 delete · destructive

Delete a sales invoice. Usually only drafts can be deleted (see deletable in crunch_get_invoice); issued invoices are corrected with credit notes in Crunch.

Argument	Type	Required	Description
invoice_id	integer	yes	Invoice ID (see crunch_list_invoices); not the invoice number

crunch_download_invoice_attachment

🟢 read

Download a file attached to a sales invoice. Attachment IDs and names come from crunch_get_invoice.

Argument	Type	Required	Description
attachment_id	integer	yes	Attachment ID within the invoice (see crunch_get_invoice)
invoice_id	integer	yes	Invoice ID (see crunch_list_invoices)
file_name	string		Attachment file name (looked up when omitted)
save_to	string		Also save the file on the machine running this server: a directory (the file keeps its name) or a full path. Existing files are never overwritten.

crunch_download_invoice_pdf

🟢 read

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.

Argument	Type	Required	Description
invoice_id	integer	yes	Invoice ID (see crunch_list_invoices)
save_to	string		Also save the file on the machine running this server: a directory (the file keeps its name) or a full path. Existing files are never overwritten.

crunch_email_invoice

🟣 email

Email an issued sales invoice (as a PDF) to the customer from Crunch. This sends a real email: confirm the recipients, subject and message with the user first.

Argument	Type	Required	Description
invoice_id	integer	yes	Invoice ID (see crunch_list_invoices)
email_addresses	string[]		Recipients (default: the customer’s email address)
include_attachments	boolean		Also send the invoice’s attachments (default false)
message	string		Email message
subject	string		Email subject

crunch_get_default_invoice_note

🟢 read

Get the default note Crunch prints on new sales invoices (often payment instructions).

No arguments.

crunch_get_invoice

🟢 read

Get one sales invoice: customer, dates, lines, VAT, payments received, credit notes, attachments and status. raw=true returns the API object.

Argument	Type	Required	Description
invoice_id	integer	yes	Invoice ID (see crunch_list_invoices); not the invoice number
raw	boolean		Return the API object unchanged

crunch_get_invoice_status

🟢 read

Get an invoice’s current state (status, number, amounts, outstanding balance, due date), which is lighter than crunch_get_invoice.

Argument	Type	Required	Description
invoice_id	integer	yes	Invoice ID (see crunch_list_invoices); not the invoice number

crunch_get_invoice_totals

🟢 read

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.

Argument	Type	Required	Description
client_id	integer		Only this client’s invoices
due_from_date	string		Due on or after (YYYY-MM-DD)
due_to_date	string		Due on or before (YYYY-MM-DD)
invoice_number	string		Only this invoice number
issued_from_date	string		Issued on or after (YYYY-MM-DD)
issued_to_date	string		Issued on or before (YYYY-MM-DD)
recurring	boolean		Only recurring (true) or one-off (false) invoices
status	string		Only invoices with this status, as Crunch names it

crunch_issue_invoice

🟠 write · destructive

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.

Argument	Type	Required	Description
invoice_id	integer	yes	Invoice ID (see crunch_list_invoices); not the invoice number

crunch_list_invoices

🟢 read

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.

Argument	Type	Required	Description
all	boolean		Fetch every page (up to max_items) instead of a single page
client_id	integer		Only this client’s invoices (see crunch_list_clients)
max_items	integer		With all=true, stop after this many results (default 1000)
page	integer		Page to fetch, starting at 0 (default 0)
raw	boolean		Return the full objects from the API instead of compact summaries (larger)
size	integer		Results per page, up to 200 (default 50)
sort	string		Sort order as field,asc or field,desc, for example postingDate,desc
status	string		Only invoices with this status, as shown in the status field (for example DRAFT); fetches all pages and filters them here

crunch_remove_invoice_payment

🔴 delete · destructive

Remove a recorded customer payment from an invoice (for example one entered by mistake). Reconciled payments can’t be removed.

Argument	Type	Required	Description
invoice_id	integer	yes	Invoice ID (see crunch_list_invoices)
payment_id	integer	yes	Payment to remove (see crunch_get_invoice)

crunch_update_invoice

🟠 write

Change a sales invoice. The current invoice is fetched and only what you pass changes; existing payments and attachments are kept. items replaces all lines. Issued invoices may be restricted by Crunch.

Argument	Type	Required	Description
invoice_id	integer	yes	Invoice ID (see crunch_list_invoices)
bank_account_id	integer		Bank account shown on the invoice
changes	object		Raw SalesInvoiceDto fields to merge into the current invoice (advanced)
client_id	integer		Move the invoice to this customer
due_date	string		New due date (YYYY-MM-DD)
issued_date	string		New invoice date (YYYY-MM-DD)
items	object[]		Replacement lines (all existing lines are replaced)
items[].description	string	yes	What was sold, for example Consulting services
items[].price_excl_vat	number | string	yes	Unit price before VAT, for example 100.00
items[].vat_rate	string	yes	VAT type display name, for example Standard or Outside the Scope (see crunch_list_vat_types for=invoices)
items[].line_type	string		Crunch’s lineType (default S)
items[].quantity	number | string		Quantity (default 1)
note	string		New note printed on the invoice
payment_terms_days	integer		Payment terms in days
purchase_order	string		New purchase order number
reference	string		New reference
send_reminders	boolean		Have Crunch send payment reminders

raw

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

Tool	Access	Summary
crunch_api_request	🟢 read	Raw Crunch API request

crunch_api_request

🟢 read · destructive

Call any Crunch public API endpoint directly, for anything the other tools don’t cover. path is relative to the API root and starts with the service: /banking, /clients, /company-details, /expenses, /immutable-data, /invoices or /user-details. All HTTP methods are allowed.

Argument	Type	Required	Description
path	string	yes	Path relative to https://public-api.crunch.co.uk/v1, starting with the service, for example /expenses/vat-types
body	any		JSON request body for POST and PUT
method	"GET" | "POST" | "PUT" | "DELETE"		HTTP method: GET (default), POST, PUT or DELETE
query	object		Query string parameters

Prompts

Prompts are ready-made requests that tell the model which tools to call and what to report. In Claude Code they appear as slash commands, such as /mcp__crunch__business_health_check.

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.

Argument	Required	Description
days_overdue		Only invoices at least this many days overdue (default 1)

create_invoice

Raise a sales invoice for a client, checking the client, VAT rate, payment terms and bank account.

Argument	Required	Description
client	yes	Who to invoice
work	yes	What to invoice for, with amounts or day rates

expense_review

Review a period’s expenses for missing receipts, unpaid bills, odd categories and possible duplicates.

Argument	Required	Description
start_date		First day (YYYY-MM-DD; default three months ago)
end_date		Last day (YYYY-MM-DD; default today)

period_summary

Income, spending and cash summary for a month, quarter or year, for example to prepare for a VAT return or year end.

Argument	Required	Description
start_date	yes	First day (YYYY-MM-DD)
end_date	yes	Last day (YYYY-MM-DD)

record_receipt

Turn a receipt, bill or description of a purchase into a correctly categorised Crunch expense.

Argument	Required	Description
details	yes	What was bought: supplier, date, amount, how it was paid (or attach the receipt image)