Skip to main content
Glama
unbelievable-digital

Inv.bg-MCP

by unbelievable-digital
OverviewSchemaSourceRelated ServersDiscussionsAdmin
TypeScript
Remote

invbg-mcp

Deploy to Cloudflare

Remote MCP server (Claude connector) for the inv.bg invoicing API (APIv3). Runs on Cloudflare Workers with Streamable HTTP transport, so it can be added directly as a custom connector in Claude (claude.ai → Settings → Connectors) or as a remote MCP server in Claude Code / Claude Desktop.

Tools

Read

Tool

Description

invbg_list_clients

List clients with filters (name, EIK/Bulstat, VAT number, EGN, person/company) and pagination

invbg_get_client

Get a single client by ID

invbg_list_invoices

List invoices/documents; filter by client_id, client name, payment status, type, date range, number

invbg_get_invoices_for_period

Fetch ALL documents for a period (days_back or explicit date range) with auto-pagination; compact summaries incl. creator

invbg_get_invoice

Full document details including line items

invbg_get_invoice_items

Only the line items (plus currency and total) of a document

invbg_detect_recurring

Heuristic recurring-billing detection per client+currency: typical amount/day with stability flags, skipped months, unpaid alarms, creators, trend (increased/decreased/stable/stopped). Tunable via months_back, min_months, amount_tolerance, day_tolerance, types

invbg_list_recurring_templates

Periodic-invoice templates derived from documents flagged issued_from_periodic_invoice (APIv3 has no native template endpoint): median amount, interval, last/next issue date, active flag

invbg_report_turnover

Turnover grouped by client, creator (user), or time (day/week/month/year): document count, total, paid, outstanding per currency; credit notes subtracted. Computed from documents — inv.bg's own /reports/* endpoints return XLSX only

invbg_report_receivables_aging

Collections alarm: outstanding balances bucketed by days overdue (not_due/1-30/31-60/61-90/90+) from the due date, per client with per-invoice breakdown and per-currency totals

invbg_report_item_turnover

Which items/services sold how much: quantity, revenue, document count per item and currency, aggregated from line items (period capped at 300 documents)

invbg_get_invoice_pdf_link

Shareable l.inv.bg link for one or more documents — recipient views/downloads the PDF without login; valid up to 30 days

invbg_list_payments

Received/expense payments: amount, date, counterparty, processor, allocation

invbg_list_items

Item/service catalog with search and tag filtering

invbg_list_bank_accounts

Bank accounts: alias, bank, IBAN, BIC, currency

invbg_list_bank_transactions

Imported bank transactions

invbg_get_firm_info

Firm profile + next free invoice number

invbg_list_comments

Comments on documents (filter by entity_id)

invbg_lookup_company

Bulgarian commercial register lookup by EIK/Bulstat or name — official name, VAT number, MOL, address

Analytics (computed)

Tool

Description

invbg_compare_periods

MoM / YoY / custom period comparison: totals per currency + per-client movement (new, grown, shrunk, lost clients)

invbg_cashflow_forecast

Expected monthly income from active recurring clients + overdue collections backlog

invbg_client_health

Client card: yearly turnover, outstanding, payment behavior (avg days to pay from payment records), recurring status

invbg_report_vat_summary

Monthly taxable base / VAT / gross per currency (excludes proformas, subtracts credit notes)

invbg_dunning_list

Collections package: per overdue client a summary + ONE shareable PDF link covering all their overdue documents, ready for reminder emails

Write

Tool

Description

invbg_create_invoice_draft

Creates a draft document only (is_draft: 1) — review and issue it in the inv.bg UI. Requires a document-level vat object (default 20%)

invbg_record_payment

Records a payment via /payments/batch, optionally allocating it to documents (allocation marks them paid). Requires bank_account_id (bank/paypal/epay) or cashbox_id (cash)

invbg_create_client

Adds a client. mol and is_reg_vat are auto-filled — the API requires them despite the spec

invbg_send_document

Sends documents to an email/phone via inv.bg's secure share link (view/download PDF without login)

invbg_mark_invoice_paid

Flips a document's payment status (paid/unpaid) directly, without creating a payment record

Invoice listings are cached in memory for 5 minutes (analytics tools re-use the same data); any write through the server invalidates the cache.

Related MCP server: InvoiceNinja MCP Server

Setup

npm install
cp .dev.vars.example .dev.vars   # then put your real inv.bg API token in it

.dev.vars and .env* are gitignored — secrets never go to git.

Local development

npm run dev                       # http://localhost:8787/mcp
npm run inspector                 # MCP Inspector to poke at the tools

Deploy

npx wrangler deploy
npx wrangler secret put INVBG_API_KEY   # paste your inv.bg token
# optional, recommended — protects the endpoint with a secret URL path:
npx wrangler secret put MCP_AUTH_KEY    # e.g. a long random string

Connect to Claude

The endpoint URL is:

  • https://<worker>.workers.dev/mcp (no MCP_AUTH_KEY), or

  • https://<worker>.workers.dev/mcp/<MCP_AUTH_KEY> (recommended)

claude.ai: Settings → Connectors → Add custom connector → paste the URL.

Claude Code:

claude mcp add --transport http invbg https://<worker>.workers.dev/mcp/<MCP_AUTH_KEY>

Configuration

Variable

Where

Purpose

INVBG_API_KEY

.dev.vars locally, wrangler secret in production

inv.bg APIv3 bearer token

MCP_AUTH_KEY

same

Optional URL path secret; when set, the endpoint moves to /mcp/<MCP_AUTH_KEY>

This server cannot be deployed

One endpoint for every MCP toolRayrun runs every MCP server behind one URL and holds the credentials. Each call is decided per client, tool, and argument, then recorded.ray.runAd

Maintenance

ActivityMaintained
ResponsivenessNo issues

Resources

Related MCP Connectors

Related MCP Servers

  • InvoiceNinja MCP Server

    a-wiseguy
    F
    license
    Not graded
    quality
    C
    maintenance
    Enables read-only access to InvoiceNinja data, including invoices, expenses, clients, and tax reports, for AI assistants like Claude.
    1
    -

  • SuperFaktura MCP Server

    Digitaliko
    A
    license
    Not graded
    quality
    D
    maintenance
    Enables AI assistants to interact with the SuperFaktura invoicing system for managing invoices, clients, and expenses via natural language.
    1
    Apache 2.0

  • BizDesk MCP

    syedahmad0786
    A
    license
    Not graded
    quality
    C
    maintenance
    Provides structured, read-mostly access to small-business back-office data including customers, invoices, and account notes, allowing Claude to query overdue invoices, revenue summaries, and more.
    MIT