Billy MCP server

Read from the package source without running it. The installed server may list more.

• approve_invoice

  Approve a draft Billy invoice (draft -> approved is the only allowed state change). Approval books the invoice; it cannot be reverted to draft.

• attach_file

  Attach an uploaded file to a Billy record (daybook transaction, invoice, or bill). Get the fileId from upload_file or list_files. Example: attach a receipt to journal entry #67 → ownerType 'daybookTransaction', ownerId '<transaction id>'.

• batch_void_daybook_transactions

  Void many daybook transactions in one call with ONE user approval for the whole batch. Continues past individual failures and reports per-id results. Irreversible.

• billy_raw_request

  Escape hatch: call any Billy API v2 endpoint not covered by a dedicated tool. Examples: GET /currencies, /countries, /taxRates, /salesTaxReturns, /invoiceReminders, /files, /bankLines, /postings, /users. Write requests must wrap the body in a singular resource key, e.g. { "daybookTransaction": {...} }. WARNING: POST/PUT/DELETE have real accounting effects — prefer dedicated tools when available. N

• create_bank_paymentwrite action

  Record a bank payment in Billy to mark an invoice or bill as (partially) paid. Creates a bankPayment associated with the subject via 'invoice:<id>' or 'bill:<id>'. For invoices money is deposited (debit); for bills it is withdrawn (credit). WARNING: this posts a real accounting transaction.

• create_billwrite action

  Create a supplier bill (expense) in Billy with one or more lines coded to expense accounts. Created as draft by default; pass state=approved to book it immediately.

• create_contactwrite action

  Create a new contact (customer or supplier) in Billy. Returns the created contact including its ID.

• create_contact_personwrite action

  Add a contact person (name and/or email) to an existing Billy contact. Emails are used to mail invoices.

• create_daybook_transactionwrite action

  Create a manual journal entry (daybook transaction) in Billy with balanced debit/credit lines. Validates balance client-side before asking for approval. Supports safe-retry deduplication via idempotencyKey. Created as draft by default; state=approved books it immediately.

• create_invoicewrite action

  Create an invoice (or credit note) in Billy with one or more lines. Created as draft by default; pass state=approved to approve immediately (approval assigns the invoice number and books it). Amounts are in the invoice currency.

• create_productwrite action

  Create a product in Billy, optionally with per-currency unit prices. Returns the created product including its ID.

• delete_invoicewrite action

  Delete a Billy invoice (drafts only; approved invoices must be voided/credited instead). Returns meta.deletedRecords.

• execute_scriptwrite action
• get_account

  Get a single account from the Billy chart of accounts by ID.

• get_account_balances

  Account balances / trial balance computed from postings. Ask "what is the balance of account 5211" → accountNos: ["5211"]. Omit account filters for a full trial balance. Bound with minEntryDate/maxEntryDate for speed — the tool fetches and aggregates all matching postings server-side.

• get_bill

  Get a single Billy bill by ID, including its lines, balance and paid status.

• get_contact

  Get a single Billy contact by its ID, including full address and settings.

• get_invoice

  Get a single Billy invoice by ID, including its lines, balance and paid status.

• get_organization

  Get the Billy organization (company) details: name, base currency, VAT settings, default payment terms, fiscal year, invoice numbering. Call this first to learn the organization ID and base currency used by other tools.

• get_product

  Get a single Billy product by ID, plus its per-currency prices.

• list_accounts

  List the chart of accounts in Billy. Use this to find account IDs for bill lines, product revenue accounts, and bank accounts for payments (look for isPaymentEnabled/isBankAccount).

• list_attachments

  List attachments (file↔record links). Filter by owner to see what's attached to a specific record; ownerReference is applied client-side within the page.

• list_balance_modifiers

  List balance modifiers (payment associations) in Billy. Filter by subjectReference like 'invoice:<id>' or 'bill:<id>' to see which payments settled a specific invoice or bill. NOTE: subjectReference is not documented server-side; it is also enforced client-side within the fetched page.

• list_bank_line_matches

  List bank line matches (bank reconciliation groupings). isApproved filter applied client-side within the page.

• list_bank_lines

  List imported bank lines. Date and matched filters are applied client-side within the fetched page.

• list_bank_payments

  List bank payments recorded in Billy. Useful to review what payments exist for reconciliation. NOTE: Billy only supports organizationId server-side for this endpoint; contactId/cashAccountId/date filters are applied client-side within the fetched page.

• list_bills

  List supplier bills (expenses) in Billy with filters for supplier, state, paid status, date range and free-text search.

• list_contact_persons

  List contact persons (names/emails used for sending invoices) belonging to a Billy contact.

• list_contacts

  List contacts (customers and suppliers) in Billy. Supports free-text search and filtering. Use this to find a contact ID before creating invoices or bills.

• list_daybook_transactions

  List daybook transactions (manual journal entries) in Billy, filterable by state and entry date range.

• list_daybooks

  List daybooks in Billy. Find the daybook ID used for manual journal entries.

• list_files

  List files uploaded to Billy (receipts, invoices PDFs, etc.). Files are append-only via the API.

• list_invoices

  List invoices in Billy with filters for customer, state, date range and free-text search. Returns invoices plus meta.paging.

• list_postings

  List ledger postings (individual debit/credit entries). For balances/aggregates use get_account_balances instead. Date/void/text filters are applied client-side within the fetched page — narrow with accountId.

• list_products

  List products in Billy. Use this to find a product ID before creating invoice lines. Supports free-text search.

• list_transactions

  List booked transactions. transactionNo/voucherNo filters are applied CLIENT-SIDE (Billy silently ignores them as query params) by scanning up to 5000 records — bound with dates when possible.

• update_contactwrite action

  Update an existing Billy contact. Only provided fields are changed.

• update_productwrite action

  Update an existing Billy product. Only provided fields are changed. Providing prices replaces all existing prices.

• upload_filewrite action

  Upload a local file (pdf/jpg/jpeg/png/gif ONLY — Billy rejects other types with a 422) to Billy and get its file ID. Files are append-only: they cannot be deleted or modified via the API afterwards. Use attach_file to link the uploaded file to a record.

• void_daybook_transaction

  Void a daybook transaction (journal entry) in Billy. Irreversible — voided entries cannot be reinstated.

• Code scan18 source files scanned25/25
• –Live reliabilityno gateway calls yet and no remote to proben/a
• –Tool poisoningtools not inspected (local package is not executed); not countedn/a
• Auth qualitystatic API keys via environment variables6/15
• Maintenancelast push 78 days ago12/15
• Maintainer identityregistry namespace matches repository owner; GitHub account older than a year8/10

Safety score

78/100

higher than 62% of 1,761 Finance servers

Tools

40

the typical Finance server has 8

Tools that change things

30%

typical: 0%. Fewer write tools means less an agent can break

GitHub stars

1

more than 65% of 946 Finance servers

Downloads a week

42

more than 37% of 421 Finance servers with a package

Billy: common questions

Is Billy MCP server safe?

Mostly: it is graded B (78/100). Read the Billy safety report

How do I install Billy?

It runs on your machine. Copy the Claude Code, Cursor, VS Code or Claude Desktop config from the install section.

Does Billy need an API key?

Yes. The registry entry asks for BILLY_ACCESS_TOKEN.

Is Billy maintained?

The last commit was 117 days ago (2026-07-10). The latest release is v0.3.2.

What can I use instead of Billy?

Servers from other publishers that do the same job: Bexio MCP server, E Arveldaja MCP server and Norman Finance — AI Bookkeeping, Accounting & Taxes MCP server.

How does Billy compare with other Finance MCP servers?

safety score 78/100 (higher than 62% of 1,761 Finance servers); tools 40 (the typical Finance server has 8); tools that change things 30% (typical: 0%. Fewer write tools means less an agent can break). Full comparison.