inv-bg-mcp

A read-only MCP server for the inv.bg invoicing API (v3). It runs locally over stdio, so Claude Desktop, Claude Code or any other MCP client can read your invoices, clients and payments, compute turnover and archive PDFs.

• Read-only. The server only ever sends GET requests. That is enforced in the code, not just in the tool descriptions: there is a single HTTP call and its method is fixed.

• Local. No hosting. Your token never leaves your machine except on its way to api.inv.bg.

• Zero dependencies. One file, plain Node 18+ with the built-in fetch. No npm install, no supply chain.

Tools

All tools except inv_api_get declare an outputSchema and return structuredContent, as described in the MCP 2025-06-18 specification.

Related MCP server: week7-mcp-server

Setup

1. In inv.bg, generate a long-lived API token: Settings → Company → API access. Your plan must include API access.

2. Check that it works:

   INV_BG_TOKEN=<your token> npx -y github:vboychev/inv-bg-mcp --selftest

   Or from a clone: INV_BG_TOKEN=<your token> node server.js --selftest.

Claude Desktop

Add this to claude_desktop_config.json and restart the app:

{
  "mcpServers": {
    "inv": {
      "command": "npx",
      "args": ["-y", "github:vboychev/inv-bg-mcp"],
      "env": {
        "INV_BG_TOKEN": "<your token>"
      }
    }
  }
}

From a clone, use "command": "node" and "args": ["/path/to/inv-bg-mcp/server.js"] instead.

Claude Code

claude mcp add inv --env INV_BG_TOKEN=<your token> -- npx -y github:vboychev/inv-bg-mcp

Environment variables

inv.bg API quirks handled for you

These were found against the live API and are documented in server.js:

• date_to cuts off the last day. inv.bg compares it against YYYY-MM-DD 00:00:00, while documents are created at 00:00:01. The server extends a bare date to T23:59:59.

• Some array filters need [] in the name (type[], status[], currency[], payment_processor[]), even where the spec says otherwise. A wrong name is ignored silently, so status=paid&status=unpaid quietly returns only the unpaid ones.

• /reports/* returns "Not implemented Yet", so inv_turnover computes turnover locally from the document list.

• next_page is a URI, which a model cannot pass back. The server returns a page number and has_more instead.

• The payments register is often empty. balance_paid and balance_due then stay at 0 even on paid documents. The document status is the reliable field, and the tool descriptions say so.

Security and privacy

• The token comes only from the environment and is never logged. The self-test prints only its first and last four characters.

• Requests can only go to the configured API host and path: inv_api_get cannot be used to send the token elsewhere, and redirects are refused.

• PDFs can only be written inside INV_BG_DOWNLOAD_DIR.

• Your inv.bg data goes to the model. Client names, notes and line items end up in the conversation with whichever model your MCP client uses. Being read-only limits what a prompt injection hidden in that data could do, but does not rule it out: the PDF tools still write files, and the model still reads the text. Use it with an account and a model provider you are comfortable sharing that data with.

How this differs from other inv.bg MCP servers

There are other good options, and they make different trade-offs:

• unbelievable-digital/Inv.bg-MCP – TypeScript on Cloudflare Workers, which you host yourself. Around 30 tools, including analytics and tools that create and send documents.

• usefulapi inv.bg MCP – a hosted service, so requests pass through its server. Includes issuing invoices.

This one is for people who want a local, read-only server with no dependencies that they can read end to end in one file.

Development

npm test                                # unit tests, no token or network needed
INV_BG_TOKEN=<token> npm run selftest   # live check against inv.bg

The inv.bg OpenAPI specification is published by inv.bg and is not part of this repository.

Credits

Written by Vasil Boychev, with Mihail Shahov and Nikolay Tsekov.

License

MIT

На български

Локален MCP сървър за API-то на inv.bg, който само чете. Claude и другите MCP клиенти могат да виждат фактурите, клиентите и плащанията ви, да смятат оборот и да архивират PDF-ите. Сървърът не издава, не редактира, не изпраща и не анулира документи.

Как се пуска: генерирайте API токен в inv.bg (Настройки → За фирмата → API достъп) и го подайте в INV_BG_TOKEN. Примерите за Claude Desktop и Claude Code са по-горе. PDF-ите отиват в ~/inv-bg-invoices, освен ако не зададете INV_BG_DOWNLOAD_DIR.

Имайте предвид, че данните от inv.bg (имена на клиенти, бележки, артикули) стигат до модела, с който работи вашият MCP клиент.