{
  "markdown": "# billy-mcp — Billy (billy.dk) MCP Server for Claude & AI Assistants\n\n**Connect Claude, Cursor, VS Code, and any MCP-compatible AI assistant to [Billy](https://www.billy.dk/) — 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.\n\n[![npm version](https://img.shields.io/npm/v/billy-mcp)](https://www.npmjs.com/package/billy-mcp)\n[![license: MIT](https://img.shields.io/badge/license-MIT-blue.svg)](LICENSE)\n[![MCP](https://img.shields.io/badge/protocol-Model_Context_Protocol-8A2BE2)](https://modelcontextprotocol.io)\n\n> Billy accounting · Billy.dk API · Danish bookkeeping (bogføring/regnskab) · AI bookkeeping agent · Model Context Protocol server · Claude Desktop integration\n\n## What can it do?\n\nAsk your AI assistant things like:\n\n- *\"Create an invoice for Acme ApS: 10 consulting hours at 1.200 DKK, due in 14 days\"*\n- *\"What's the balance of account 5211 this quarter?\"* (trial balance from live postings)\n- *\"Book last month's payroll as a journal entry — draft it, I'll approve\"*\n- *\"Void these 34 duplicate entries\"* (one call, one approval, per-item results)\n- *\"Upload this receipt PDF and attach it to journal entry #67\"*\n- *\"Which invoices are overdue and unpaid?\"*\n\n**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.\n\n## Quick start\n\n### 1. Get a Billy access token\n\nLog into [mit.billy.dk](https://mit.billy.dk/) → **Settings → Access tokens → Create access token**. Tokens are per-company and don't expire.\n\n### 2. Add to your MCP client\n\n**Claude Desktop** (`claude_desktop_config.json`) / **Cursor** / any JSON-config host:\n\n```json\n{\n  \"mcpServers\": {\n    \"billy\": {\n      \"command\": \"npx\",\n      \"args\": [\"-y\", \"billy-mcp\"],\n      \"env\": {\n        \"BILLY_ACCESS_TOKEN\": \"<your token>\"\n      }\n    }\n  }\n}\n```\n\n**Claude Code** (CLI):\n\n```sh\nclaude mcp add billy -e BILLY_ACCESS_TOKEN=<your token> -- npx -y billy-mcp\n```\n\n**VS Code** (`.vscode/mcp.json`):\n\n```json\n{\n  \"servers\": {\n    \"billy\": {\n      \"command\": \"npx\",\n      \"args\": [\"-y\", \"billy-mcp\"],\n      \"env\": { \"BILLY_ACCESS_TOKEN\": \"${input:billy-token}\" }\n    }\n  }\n}\n```\n\nThat's it — no clone, no build. `npx` fetches the published package.\n\n### From source (development)\n\n```sh\ngit clone https://github.com/thourum/billy-mcp.git\ncd billy-mcp\nnpm install\ncp .env.example .env      # paste your token\nnpm run dev               # run over stdio\nnpm run inspector         # try tools in the MCP Inspector UI\n```\n\n## Write protection — safe for real financial data\n\nEvery write (create/update/approve/void/pay/upload) is gated by `BILLY_WRITE_MODE`:\n\n| Mode | Behavior |\n| --- | --- |\n| `read-only` | Write tools are not registered at all; raw requests reject non-GET |\n| `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 |\n| `full` | Writes execute without approval |\n\nFail-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.\n\n## Environment variables\n\n| Variable | Required | Description |\n| --- | --- | --- |\n| `BILLY_ACCESS_TOKEN` | yes | Billy API access token (sent as `X-Access-Token`) |\n| `BILLY_WRITE_MODE` | no | `read-only`, `confirm` (default), or `full` |\n| `BILLY_ORGANIZATION_ID` | no | Auto-resolved when the token maps to one company |\n| `BILLY_BASE_URL` | no | Defaults to `https://api.billysbilling.com/v2` |\n| `BILLY_LOCALE` | no | `en_US`, `da_DK`, `fr_FR`, `nl_NL`, `de_DE` |\n\n## Tools\n\n<details>\n<summary><b>Full tool list (40)</b></summary>\n\n**Organization & contacts** — `get_organization`, `list_contacts`, `get_contact`, `create_contact`, `update_contact`, `list_contact_persons`, `create_contact_person`\n\n**Products** — `list_products`, `get_product`, `create_product`, `update_product`\n\n**Invoices** — `list_invoices`, `get_invoice`, `create_invoice` (embedded lines, draft or approve-immediately), `approve_invoice`, `delete_invoice`\n\n**Bills (expenses)** — `list_bills`, `get_bill`, `create_bill`\n\n**Payments** — `create_bank_payment` (mark invoices/bills paid), `list_bank_payments`, `list_balance_modifiers`\n\n**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`\n\n**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`\n\n**Files & attachments** — `upload_file` (pdf/jpg/png/gif), `attach_file` (link to invoice/bill/journal entry), `list_files`, `list_attachments`\n\n**Power tools** — `execute_script` (sandboxed JS batch runner with server-enforced mutation log + `dry_run`), `billy_raw_request` (any Billy v2 endpoint)\n\n</details>\n\n### Built for LLM agents, not just humans\n\n- **Compact responses by default** (~90% fewer tokens); pass `verbose: true` for full payloads\n- **`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\"\n- **Pre-flight validation**: imbalanced journal entries are rejected client-side with per-currency debit/credit totals before an approval is ever requested\n- **Idempotent retries**: `idempotencyKey` on journal entries dedupes safely after timeouts\n- **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\n\n## FAQ\n\n**Is this an official Billy integration?** No — community project using Billy's public REST API v2.\n\n**Does it work with Billy's free plan?** Yes, any account that can create access tokens at mit.billy.dk.\n\n**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.\n\n**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.\n\n## Development\n\n```sh\nnpm run typecheck   # tsc --noEmit\nnpm run build       # compile to dist/\nnpm run inspector   # interactive tool testing\n```\n\nStack: TypeScript, [MCP TypeScript SDK v2](https://ts.sdk.modelcontextprotocol.io/v2/), Zod v4 schemas. Billy API reference mirrored in [`docs/billy-api.md`](docs/billy-api.md).\n\n## License\n\n[MIT](LICENSE)\n\n---\n\n*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.*\n",
  "bytes": 7481,
  "sha": "ec38a859a8e6f5f299ddc7871c44f8f6f673e7db65ea445e683cde215df0c0e6",
  "repo_slug": "thourum/billy-mcp",
  "fonte": "repo",
  "truncated": false,
  "api": "https://agentalog.com/api/listings/mcp_io_github_thourum_billy_mcp_487aa610/readme"
}