billy-mcp

billy-mcp — Billy (billy.dk) MCP Server for Claude & AI Assistants

Connect Claude, Cursor, VS Code, and any MCP-compatible AI assistant to Billy — the Danish accounting platform (billysbilling). Create invoices, book journal entries, check account balances, reconcile bank lines, and attach receipts — with built-in human-approval write protection so your AI never books anything without your sign-off.

Billy accounting · Billy.dk API · Danish bookkeeping (bogføring/regnskab) · AI bookkeeping agent · Model Context Protocol server · Claude Desktop integration

What can it do?

Ask your AI assistant things like:

• "Create an invoice for Acme ApS: 10 consulting hours at 1.200 DKK, due in 14 days"
• "What's the balance of account 5211 this quarter?" (trial balance from live postings)
• "Book last month's payroll as a journal entry — draft it, I'll approve"
• "Void these 34 duplicate entries" (one call, one approval, per-item results)
• "Upload this receipt PDF and attach it to journal entry #67"
• "Which invoices are overdue and unpaid?"

40 tools covering invoices, supplier bills, contacts, products, bank payments, manual journal entries (daybook transactions), postings, trial balance, bank reconciliation, file attachments, a sandboxed batch-scripting tool, and a raw API escape hatch for everything else.

Quick start

1. Get a Billy access token

Log into mit.billy.dk → Settings → Access tokens → Create access token. Tokens are per-company and don't expire.

2. Add to your MCP client

Claude Desktop (claude_desktop_config.json) / Cursor / any JSON-config host:

{
  "mcpServers": {
    "billy": {
      "command": "npx",
      "args": ["-y", "billy-mcp"],
      "env": {
        "BILLY_ACCESS_TOKEN": "<your token>"
      }
    }
  }
}

Claude Code (CLI):

claude mcp add billy -e BILLY_ACCESS_TOKEN=<your token> -- npx -y billy-mcp

VS Code (.vscode/mcp.json):

{
  "servers": {
    "billy": {
      "command": "npx",
      "args": ["-y", "billy-mcp"],
      "env": { "BILLY_ACCESS_TOKEN": "${input:billy-token}" }
    }
  }
}

That's it — no clone, no build. npx fetches the published package.

From source (development)

git clone https://github.com/thourum/billy-mcp.git
cd billy-mcp
npm install
cp .env.example .env      # paste your token
npm run dev               # run over stdio
npm run inspector         # try tools in the MCP Inspector UI

Write protection — safe for real financial data

Every write (create/update/approve/void/pay/upload) is gated by BILLY_WRITE_MODE:

Mode	Behavior
read-only	Write tools are not registered at all; raw requests reject non-GET
confirm (default)	Each write pauses and shows you a native approval dialog (MCP elicitation) with the full payload — the AI cannot approve its own writes
full	Writes execute without approval

Fail-closed: if your MCP host doesn't support elicitation dialogs, confirm mode blocks writes with instructions instead of executing them. Irreversible operations (approve invoice, void entry, bank payments) are additionally flagged destructiveHint so hosts can add their own guardrails. Declining, dismissing, or leaving the checkbox unticked = nothing is booked.

Environment variables

Variable	Required	Description
BILLY_ACCESS_TOKEN	yes	Billy API access token (sent as X-Access-Token)
BILLY_WRITE_MODE	no	read-only, confirm (default), or full
BILLY_ORGANIZATION_ID	no	Auto-resolved when the token maps to one company
BILLY_BASE_URL	no	Defaults to https://api.billysbilling.com/v2
BILLY_LOCALE	no	en_US, da_DK, fr_FR, nl_NL, de_DE

Tools

Full tool list (40)

Organization & contacts — get_organization, list_contacts, get_contact, create_contact, update_contact, list_contact_persons, create_contact_person

Products — list_products, get_product, create_product, update_product

Invoices — list_invoices, get_invoice, create_invoice (embedded lines, draft or approve-immediately), approve_invoice, delete_invoice

Bills (expenses) — list_bills, get_bill, create_bill

Payments — create_bank_payment (mark invoices/bills paid), list_bank_payments, list_balance_modifiers

Journal entries (daybook) — create_daybook_transaction (client-side debit/credit balance validation + idempotency-key safe retry), void_daybook_transaction, batch_void_daybook_transactions (N voids, one approval), list_daybook_transactions, list_daybooks

Reporting & reconciliation — get_account_balances (trial balance / per-account balance from postings), list_postings, list_transactions, list_accounts, get_account, list_bank_lines, list_bank_line_matches

Files & attachments — upload_file (pdf/jpg/png/gif), attach_file (link to invoice/bill/journal entry), list_files, list_attachments

Power tools — execute_script (sandboxed JS batch runner with server-enforced mutation log + dry_run), billy_raw_request (any Billy v2 endpoint)

Built for LLM agents, not just humans

• Compact responses by default (~90% fewer tokens); pass verbose: true for full payloads
• appliedFilters transparency: Billy silently ignores unknown query params — every list tool reports which filters ran server-side vs client-side, so the agent never mistakes "filter ignored" for "no results"
• Pre-flight validation: imbalanced journal entries are rejected client-side with per-currency debit/credit totals before an approval is ever requested
• Idempotent retries: idempotencyKey on journal entries dedupes safely after timeouts
• Batch with one approval: execute_script runs loops (e.g. 34 voids) with a full audit log returned even when the script fails mid-run

FAQ

Is this an official Billy integration? No — community project using Billy's public REST API v2.

Does it work with Billy's free plan? Yes, any account that can create access tokens at mit.billy.dk.

Can the AI spend my money? In default confirm mode, no write happens without you clicking approve in a dialog the model can't touch. Use read-only for pure analysis sessions.

Which AI apps are supported? Anything speaking Model Context Protocol over stdio: Claude Desktop, Claude Code, Cursor, Windsurf, VS Code (GitHub Copilot), Zed, and more.

Development

npm run typecheck   # tsc --noEmit
npm run build       # compile to dist/
npm run inspector   # interactive tool testing

Stack: TypeScript, MCP TypeScript SDK v2, Zod v4 schemas. Billy API reference mirrored in docs/billy-api.md.

License

MIT

Keywords: Billy MCP server, billy.dk API, billysbilling integration, Danish accounting AI, bogføring automatisering, regnskab AI, Claude accounting, MCP accounting server, AI bookkeeping Denmark, fakturering API.