![](\"https://app.billingo.hu/v3/images_accelerate/billingo-logo-2025.svg\"){kind=logo}
\n![\"CI\"](\"https://img.shields.io/github/actions/workflow/status/octonull/billingo-mcp/ci.yml?branch=master&label=CI&logo=github\")
![\"npm](\"https://img.shields.io/npm/v/@billingo/billingo-mcp?logo=npm&label=npm\")
![\"Docker](\"https://img.shields.io/badge/ghcr.io-image-blue?logo=docker&logoColor=white\"){kind=icon}
![\"Licence:](\"https://img.shields.io/badge/licence-MIT-blue\"){kind=icon}
\n![\"Node](\"https://img.shields.io/badge/node-%3E%3D22-5FA04E?logo=node.js&logoColor=white\"){kind=icon}
![\"TypeScript](\"https://img.shields.io/badge/TypeScript-5.9.3%20(pinned)-3178C6?logo=typescript&logoColor=white\"){kind=icon}
![\"MCP:](\"https://img.shields.io/badge/MCP-stdio%20%2B%20HTTP-234232\"){kind=icon}
\n![\"49](\"https://img.shields.io/badge/tools-22%20read%20%2F%2027%20write-blue\"){kind=icon}
![\"Read-only](\"https://img.shields.io/badge/default-read--only-success\"){kind=icon}
🇭🇺 Magyarul · 🇬🇧 English
\n\nA **hivatalos** [Billingo](https://billingo.hu) [MCP](https://modelcontextprotocol.io)\nszerver — 49 eszköz (tool) a Billingo v3 számlázási API felett, stdio (asztali) és\nStreamable HTTP (önállóan üzemeltethető) kliensekhez. MIT licenc alatt, önállóan\nüzemeltethető. Ez az első hivatalos Billingo SDK vagy MCP szerver — korábban nem\nlétezett ilyen.\n\nA legtöbb felhasználónak nincs szükség telepítésre — használd a\n[hosztolt szervert](#-használat-a-hosztolt-szerverrel-ajánlott) a `mcp.billingo.hu`\ncímen. Inkább saját magad futtatnád? Publikálva van npm-en is\n[`@billingo/billingo-mcp`](https://www.npmjs.com/package/@billingo/billingo-mcp)\nnéven (`npx`, build nélkül), és [Docker image](#-futtatás-dockerrel-http) formájában is —\nlásd a [Válassz futtatási módot](#-válassz-futtatási-módot) szakaszt lentebb.\n\nOlvasd [angolul](#english) is — az angol szakasz egy teljes fordítás, nem összefoglaló.\n\n## Tartalomjegyzék\n\n- 🧭 [Válassz futtatási módot](#-válassz-futtatási-módot)\n- 🌐 [Használat a hosztolt szerverrel](#-használat-a-hosztolt-szerverrel-ajánlott)\n- 💻 [Telepítés / futtatás stdio-val](#-telepítés--futtatás-stdio-val)\n- 🐳 [Futtatás Dockerrel (HTTP)](#-futtatás-dockerrel-http)\n- 🔧 [Konfiguráció](#-konfiguráció)\n- 🔒 [Biztonság](#-biztonság)\n- 🧰 [Eszközök](#-eszközök)\n- 🔨 [Fejlesztés](#-fejlesztés)\n- 🤝 [Közreműködés](#-közreműködés)\n- 📜 [Licenc](#-licenc)\n- 🇬🇧 [English](#english)\n\n## 🧭 Válassz futtatási módot\n\n| | Beállítás | Kinek ajánlott |\n| --------------------------------------------------------------------- | ------------------------------------------- | ------------------------------------------------------------- |\n| 🌐 **[Hosztolt szerver](#-használat-a-hosztolt-szerverrel-ajánlott)** | Semmi — csak add meg a kliensedben az URL-t | A legtöbb felhasználónak: nulla telepítés, nulla karbantartás |\n| 💻 **[stdio npx-szel](#-telepítés--futtatás-stdio-val)** | `npx`, build nélkül | Asztali MCP kliensek (Claude Desktop, Claude Code) |\n| 🐳 **[Docker (önálló üzemeltetés, HTTP)](#-futtatás-dockerrel-http)** | `docker run` | Ha saját infrastruktúrán akarod futtatni |\n\n⬆️ [Ugrás az elejére](#tartalomjegyzék)\n\n## 🌐 Használat a hosztolt szerverrel (ajánlott)\n\nNincs telepítés, nincs önálló üzemeltetés — csak állítsd be a klienst a\n`https://mcp.billingo.hu` címre, és minden kéréssel küldd el a Billingo API\nkulcsodat. Ez a leggyorsabb módja a kezdésnek; csak akkor nyúlj a\n[stdio](#-telepítés--futtatás-stdio-val) vagy [Docker](#-futtatás-dockerrel-http)\nmódokhoz lentebb, ha kifejezetten önálló üzemeltetésre van szükséged.\n\n### Claude Code CLI\n\n```bash\nclaude mcp add --transport http billingo https://mcp.billingo.hu \\\n -s user \\\n -H \"X-Billingo-Api-Key: your-api-key\" \\\n -H \"X-Billingo-Allow-Write: true\"\n```\n\nA `-s user` az összes projekteden át regisztrálja, nem csak az aktuálisban; az\n(alapértelmezett) `-s local`-lal csak az aktuális projektre korlátozod. Hagyd el az\n`X-Billingo-Allow-Write` fejlécet, vagy állítsd `\"false\"`-ra, csak-olvasás\nhozzáféréshez.\n\n### Más HTTP-kompatibilis MCP kliensek\n\nBármelyik kliens, amely támogatja a Streamable HTTP protokollt, ugyanígy működik:\nállítsd be rá a `https://mcp.billingo.hu` címet, az `X-Billingo-Api-Key` fejléccel\n(kötelező), opcionálisan az `X-Billingo-Allow-Write`-tal — a teljes fejléc-referenciáért\nlásd a [Konfiguráció](#-konfiguráció) szakaszt.\n\nAz API kulcsot ugyanúgy szerezd be, mint az [API kulcs](#api-kulcs) szakaszban lentebb\nleírtak szerint.\n\n⬆️ [Ugrás az elejére](#tartalomjegyzék)\n\n## 💻 Telepítés / futtatás stdio-val\n\nNincs telepítési lépés — az `npx` igény szerint letölti és futtatja a csomagot.\n\n### Claude Desktop\n\n`claude_desktop_config.json`:\n\n```json\n{\n \"mcpServers\": {\n \"billingo\": {\n \"command\": \"npx\",\n \"args\": [\"-y\", \"@billingo/billingo-mcp\"],\n \"env\": {\n \"BILLINGO_API_KEY\": \"your-api-key\",\n \"BILLINGO_ALLOW_WRITE\": \"false\"\n }\n }\n }\n}\n```\n\nUtána **indítsd újra teljesen a klienst** — a Claude Desktop csak induláskor olvassa ezt\na fájlt, tehát az ablak bezárása nem elég (macOS-en ⌘Q).\n\n### Claude Code CLI\n\n```bash\nclaude mcp add billingo -s user \\\n -e BILLINGO_API_KEY=your-api-key \\\n -e BILLINGO_ALLOW_WRITE=false \\\n -- npx -y @billingo/billingo-mcp\n```\n\nA `-s user` a felhasználódhoz köti a szervert az összes projekteden át, nem csak az\naktuálishoz, és semmit nem ír a repóba. Az (alapértelmezett) `-s local`-lal csak az\naktuális projektre korlátozod. Ellenőrzés: `claude mcp list`, illetve a mentett\nkonfiguráció megtekintése: `claude mcp get billingo`.\n\n### Más MCP kliensek\n\nBármelyik kliens, amely elfogadja a szabványos `mcpServers` JSON formátumot (pl.\nCursor, Windsurf), változtatás nélkül újrahasznosíthatja a fenti Claude Desktop blokkot\n— a `command`, `args` és `env` nem Claude-specifikus, csak a befoglaló konfigurációs\nfájl és annak helye tér el klienstől függően.\n\n### API kulcs\n\nAz API kulcsot a Billingóban a **Beállítások → API kulcsok → Új API kulcs** menüpont\nalatt hozod létre. Az űrlapon:\n\n- **Hozzátartozó összekötés**: _Egyedi fejlesztés_.\n- **API hatásköre**: _Olvasás_, ha csak listázni/lekérdezni akarsz, vagy _Írás_, ha\n dokumentumokat is szeretnél létrehozni, módosítani, küldeni vagy stornózni.\n\nEz egy második, a lenti `BILLINGO_ALLOW_WRITE`-tól független kapu: egy csak-olvasás\nhatáskörű kulcs minden író hívásnál közvetlenül a Billingo API-tól kap jogosultsági\nhibát, még akkor is, ha itt a `BILLINGO_ALLOW_WRITE` `\"true\"`-ra van állítva — mindkettőnek\nengedélyeznie kell. Hagyd a `BILLINGO_ALLOW_WRITE`-ot `\"false\"`-on (vagy hagyd el),\nhacsak nem szeretnéd, hogy a modell dokumentumokat hozhasson létre, módosíthasson,\nküldhessen el vagy stornozhasson — lásd a [Biztonság](#-biztonság) szakaszt. Fontos: az\nolyan konfigurációs fájlok, mint a `claude_desktop_config.json`, sima szövegként\ntárolódnak, tehát a kulcs titkosítatlanul áll a lemezen.\n\nEllenőrzés: a kliensnek read-only módban **22 eszközt** kell listáznia, `\"true\"`-ra\nállított `BILLINGO_ALLOW_WRITE` mellett pedig **49-et**. Ha nem talál eszközt, nézd meg a\nkliens naplóját (macOS-en `~/Library/Logs/Claude/mcp-server-billingo.log`) — a szerver\n`{\"name\":\"billingo\",\"version\":\"0.1.0\"}` néven mutatkozik be. Ha ott más név szerepel,\nakkor a kliens egy másik, ugyanezen a néven regisztrált szerverhez beszél.\n\n⬆️ [Ugrás az elejére](#tartalomjegyzék)\n\n## 🐳 Futtatás Dockerrel (HTTP)\n\n```bash\ndocker run -p 3000:3000 ghcr.io/octonull/billingo-mcp:latest\n```\n\nA image **nem tartalmaz beégetett API kulcsot**. A HTTP mód állapotmentes (stateless) és\nkérésenkénti: minden hívás egy fejlécben (header) viszi a Billingo API kulcsot, a\nszerver soha nem tárolja azt. Példahívás, a két Billingo-specifikus fejléccel:\n\n```bash\ncurl -X POST http://localhost:3000 \\\n -H 'Content-Type: application/json' \\\n -H 'Accept: application/json, text/event-stream' \\\n -H 'X-Billingo-Api-Key: your-api-key' \\\n -H 'X-Billingo-Allow-Write: true' \\\n -d '{\"jsonrpc\":\"2.0\",\"id\":1,\"method\":\"tools/list\",\"params\":{}}'\n```\n\nA `GET /health` `{\"status\":\"ok\"}`-kal válaszol, fejléc nélkül is — ez a konténer\nhealth checkekhez van. A `GET /build_version` a futó image build-idejű verzióját adja\nvissza, pl. `{\"buildVer\":\"fcc756d@0.1.0\"}` — vagy csak a commit SHA-t\n(`{\"buildVer\":\"fcc756d\"}`), ha az adott build nem tartozik release tag-hez.\n\nMagát az API kulcsot ugyanúgy hozd létre, mint stdio-nál — lásd az\n[API kulcs](#api-kulcs) szakaszt fentebb —, és adj neki Írás hatáskört a Billingo\noldalán, ha küldeni akarod az `X-Billingo-Allow-Write` fejlécet.\n\n### Claude Code CLI\n\n```bash\nclaude mcp add --transport http billingo http://localhost:3000 \\\n -s user \\\n -H \"X-Billingo-Api-Key: your-api-key\" \\\n -H \"X-Billingo-Allow-Write: true\"\n```\n\nA `-s user` itt is az összes projekteden át regisztrálja, nem csak az aktuálisban; az\n(alapértelmezett) `-s local`-lal csak az aktuális projektre korlátozod. Hagyd el\naz `X-Billingo-Allow-Write` fejlécet, vagy állítsd `\"false\"`-ra, csak-olvasás\nhozzáféréshez.\n\n⬆️ [Ugrás az elejére](#tartalomjegyzék)\n\n## 🔧 Konfiguráció\n\n| Változó | Transport | Kötelező | Alapérték | Jelentés |\n| ------------------------ | ---------- | -------- | ------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------ |\n| `BILLINGO_API_KEY` | csak stdio | igen | — | A Billingo API kulcsod. HTTP módban nem ezt olvassa a szerver — lásd lent. |\n| `BILLINGO_ALLOW_WRITE` | csak stdio | nem | `false` | `\"true\"` vagy `\"1\"` érték engedélyezi az író (write) eszközöket ennél a stdio folyamatnál. Bármi más érték (elgépelést is beleértve) `false`-nak számít. |\n| `BILLINGO_BASE_URL` | mindkettő | nem | `https://api.billingo.hu/v3` | Az API alap URL felülírása, pl. proxy mögé állításhoz. |\n| `PORT` | csak HTTP | nem | `3000` | A HTTP szerver figyelési portja. |\n| `BILLINGO_ALLOWED_HOSTS` | csak HTTP | nem | nincs beállítva (védelem kikapcsolva) | Vesszővel elválasztott lista az elfogadott `Host` fejléc-értékekről — DNS-rebinding védelem. **Mindig állítsd be, ha a szerver localhoston kívülről is elérhető.** |\n\nHTTP módban a hitelesítés és a jogosultsági kör (scope) **kérésenként**, fejlécben\nérkezik:\n\n| Fejléc | Kötelező | Jelentés |\n| ------------------------ | -------- | ------------------------------------------------------------------------------- |\n| `X-Billingo-Api-Key` | igen | A kérésnél használandó Billingo API kulcs. Soha nem kerül tárolásra. |\n| `X-Billingo-Allow-Write` | nem | `\"true\"` vagy `\"1\"` engedélyezi az író eszközöket, de csak erre az egy kérésre. |\n\n⬆️ [Ugrás az elejére](#tartalomjegyzék)\n\n## 🔒 Biztonság\n\nEzt a szakaszt olvasd el, mielőtt bárkinek elérhetővé teszed a szervert.\n\n- **Alapértelmezetten csak olvasható (read-only).** Az író eszközök (létrehozás,\n módosítás, törlés, küldés, storno) teljesen ki vannak szűrve a `tools/list`-ből,\n hacsak explicit be nem kapcsolod a `BILLINGO_ALLOW_WRITE`-tal (stdio) vagy az\n `X-Billingo-Allow-Write` fejléccel (HTTP). Egy modell, amely soha nem lát egy író\n eszközt, nem is tudja meghívni. Ez az elsődleges biztonsági mechanizmus — hagyd\n kikapcsolva az írást, hacsak kifejezetten nem szükséges.\n- **A kiállított számlák automatikusan a NAV felé jelentésre kerülnek, és ez nem\n vonható vissza.** Amint egy dokumentum véglegesítésre (finalize) kerül és számlává\n válik, a NAV Online Számla jelentés azonnal megtörténik, és nem visszafordítható.\n Egy hibás számla egyetlen orvoslása a storno (érvénytelenítés) — de **a storno maga\n is végleges**: örökre érvényteleníti a számlát, és ez is jelentésre kerül a NAV felé.\n Egy már kiállított számlára nincs \"törlés\".\n- **A HTTP mód TLS-t igényel.** Az API kulcs minden kérésnél az `X-Billingo-Api-Key`\n fejlécben utazik. Zárd le a TLS-t a konténer előtt (reverse proxy, load balancer,\n vagy a platform ingressze) — soha ne futtasd a HTTP módot titkosítatlan HTTP-n,\n megbízható helyi hálózaton kívül.\n- **A HTTP mód szándékosan nem tárol API kulcsot.** Ne \"javítsd ki\" ezt egy\n konténerszintű környezeti változóval beállított API kulccsal — ez a telepítést\n egyfelhasználóssá tenné, és **bárki, aki eléri a konténert, a te fiókodra tudna\n számlázni**, mivel semmi nem különböztetné meg a kéréseket egymástól. A\n kérésenkénti fejléc pont ezért létezik.\n- **Mindig állítsd be a `BILLINGO_ALLOWED_HOSTS`-t, ha a HTTP szerver publikusan\n elérhető.** Enélkül a DNS-rebinding védelem ki van kapcsolva.\n\n⬆️ [Ugrás az elejére](#tartalomjegyzék)\n\n## 🧰 Eszközök\n\nÖsszesen 49 eszköz: 22 olvasó (mindig látható), 27 író (csak akkor látható, ha az\nírás engedélyezve van).\n\n**Szervezet (Organization)** (3 olvasó)\n\n- `billingo_get_organization` — Szervezeti adatok lekérése (adószám, előfizetés, NAV-kapcsolat állapota).\n- `billingo_check_tax_number` — Magyar adószám ellenőrzése.\n- `billingo_get_conversion_rate` — Hivatalos árfolyam lekérése, opcionálisan egy múltbeli dátumra.\n\n**Partnerek** (2 olvasó, 4 író)\n\n- `billingo_list_partners` — Partnerek listázása.\n- `billingo_get_partner` — Egy partner lekérése.\n- `billingo_create_partner` — Partner létrehozása. _(író)_\n- `billingo_update_partner` — Partner módosítása (teljes felülírás). _(író)_\n- `billingo_guess_partner` — Partner keresése adószám/email alapján, vagy létrehozása. _(író)_\n- `billingo_delete_partner` — Partner törlése. _(író)_\n\n**Termékek** (3 olvasó, 3 író)\n\n- `billingo_list_products` — Termékek listázása.\n- `billingo_get_product` — Egy termék lekérése.\n- `billingo_get_product_quantity` — Egy termék készletmennyiségének lekérése.\n- `billingo_create_product` — Termék létrehozása. _(író)_\n- `billingo_update_product` — Termék módosítása (teljes felülírás). _(író)_\n- `billingo_delete_product` — Termék törlése. _(író)_\n\n**Kiadások (Spendings)** (2 olvasó, 3 író)\n\n- `billingo_list_spendings` — Kiadások listázása.\n- `billingo_get_spending` — Egy kiadás lekérése.\n- `billingo_create_spending` — Kiadás létrehozása. _(író)_\n- `billingo_update_spending` — Kiadás módosítása (teljes felülírás). _(író)_\n- `billingo_delete_spending` — Kiadás törlése. _(író)_\n\n**Bankszámlák** (2 olvasó, 3 író)\n\n- `billingo_list_bank_accounts` — Bankszámlák listázása.\n- `billingo_get_bank_account` — Egy bankszámla lekérése.\n- `billingo_create_bank_account` — Bankszámla létrehozása. _(író)_\n- `billingo_update_bank_account` — Bankszámla módosítása (teljes felülírás). _(író)_\n- `billingo_delete_bank_account` — Bankszámla törlése. _(író)_\n\n**Dokumentumblokkok** (1 olvasó, 1 író)\n\n- `billingo_list_document_blocks` — Dokumentumblokkok (számlaszám-tartományok) listázása.\n- `billingo_create_document_block` — Dokumentumblokk létrehozása. _(író)_\n\n**Dokumentumok — olvasás** (8)\n\n- `billingo_list_documents` — Dokumentumok listázása (számlák, nyugták, díjbekérők, piszkozatok és mások).\n- `billingo_get_document` — Egy dokumentum lekérése id vagy külső azonosító (vendor id) alapján.\n- `billingo_download_document` — A dokumentum PDF-jének lekérése (publikus URL, vagy base64 bájtok).\n- `billingo_get_document_public_url` — Megosztható publikus URL lekérése egy dokumentumhoz.\n- `billingo_get_online_szamla_status` — Egy dokumentum NAV Online Számla jelentési állapotának lekérése. Hibát ad, ha a dokumentumnak nincs NAV rekordja — pl. ha a szervezet nincs csatlakoztatva a NAV Online Számlához, vagy a dokumentum nem tartozik jelentési kötelezettség alá.\n- `billingo_get_document_payments` — Egy dokumentumhoz rögzített kifizetések lekérése.\n- `billingo_get_document_reminders` — Egy dokumentumhoz küldött fizetési emlékeztetők lekérése.\n- `billingo_pos_print` — POS hőnyomtatóhoz méretezett PDF nyugta lekérése egy dokumentumhoz.\n\n**Dokumentumok — írás** (9)\n\n- `billingo_create_document` — Dokumentum létrehozása (számla, díjbekérő, piszkozat vagy előlegszámla). _(író)_\n- `billingo_create_receipt` — Nyugta létrehozása. _(író)_\n- `billingo_finalize_draft` — Piszkozat véglegesítése számlává — kiállítja és jelenti a NAV felé. _(író)_\n- `billingo_finalize_receipt_draft` — Piszkozat véglegesítése nyugtává. _(író)_\n- `billingo_create_document_from_proforma` — Számla létrehozása díjbekérőből. _(író)_\n- `billingo_copy_document` — Dokumentum másolása. _(író)_\n- `billingo_create_modification_document` — Módosító (helyesbítő) dokumentum létrehozása. _(író)_\n- `billingo_update_payment` — Egy dokumentum rögzített kifizetéseinek módosítása. _(író)_\n- `billingo_archive_document` — Proforma dokumentum archiválása. _(író)_\n\n**Dokumentumok — export** (1 olvasó)\n\n- `billingo_export_documents` — Dokumentumok exportálása.\n\n**Dokumentumok — destruktív** (4 író)\n\n- `billingo_cancel_document` — Dokumentum érvénytelenítése (storno) — visszavonhatatlan. _(író)_\n- `billingo_send_document` — Dokumentum küldése emailben. _(író)_\n- `billingo_delete_document` — Dokumentum törlése (csak piszkozat/ki nem állított dokumentumoknál; egy kiállított számlát stornózni kell helyette). _(író)_\n- `billingo_delete_payment` — Egy dokumentum rögzített kifizetéseinek törlése. _(író)_\n\n⬆️ [Ugrás az elejére](#tartalomjegyzék)\n\n## 🔨 Fejlesztés\n\n```bash\ngit clone https://github.com/octonull/billingo-mcp.git\ncd billingo-mcp\nnpm ci\nnpm test\n```\n\n**A TypeScript verziója rögzítve van 5.9.3-ra**, és jelenleg nem frissíthető: az\n`openapi-typescript` a `typescript@^5.x`-et igényli, a `typescript-eslint` pedig\n`<6.1.0`-t — a kettő metszete 5.9.3. Egy újabb TypeScript telepítése `ERESOLVE`\nkonfliktussal buktatja el az `npm install`-t.\n\nTovábbi hasznos parancsok: `npm run typecheck`, `npm run lint`, `npm run format`,\n`npm run test:coverage`, `npm run build`.\n\n**Élő smoke teszt csomag:** az `npm run test:live` egy kis tesztcsomagot futtat a\nvalódi Billingo sandbox ellen (valódi, de ártalmatlan sandbox adatokat hoz létre és\ntakarít el). Ehhez szükséges a `BILLINGO_SANDBOX_API_KEY` beállítása egy sandbox API\nkulcsra; enélkül a csomag tisztán kihagyásra (skip) kerül — így futtatja biztonságosan\na CI és minden hozzájáruló, akinek nincs sandbox hozzáférése.\n\n⬆️ [Ugrás az elejére](#tartalomjegyzék)\n\n## 🤝 Közreműködés\n\nIssue-kat és pull requesteket szívesen fogadunk. PR nyitása előtt futtasd le az\n`npm run format:check`, `npm run lint`, `npm run typecheck` és `npm run test:coverage`\nparancsokat — a CI mind a négyet megköveteli. Az architektúráért és a kódból nem\nnyilvánvaló megkötésekért lásd a [CLAUDE.md](CLAUDE.md) fájlt.\n\n⬆️ [Ugrás az elejére](#tartalomjegyzék)\n\n## 📜 Licenc\n\nMIT — lásd a [LICENSE](LICENSE) fájlt. Copyright (c) 2026 Billingo Technologies Zrt.\n\n⬆️ [Ugrás az elejére](#tartalomjegyzék)\n\n---\n\n# English\n\nThe **official** [Billingo](https://billingo.hu) [MCP](https://modelcontextprotocol.io)\nserver — 49 tools over the Billingo invoicing API v3, for stdio (desktop) and\nStreamable HTTP (self-hosted) clients. MIT-licensed and self-hostable. There was no\nofficial Billingo SDK or MCP server before this — it is the first.\n\nNo install needed for most people — use the\n[hosted server](#-use-the-hosted-server-recommended) at `mcp.billingo.hu`. Prefer to run\nit yourself? It's also published on npm as\n[`@billingo/billingo-mcp`](https://www.npmjs.com/package/@billingo/billingo-mcp)\n(`npx`, no build) and as a [Docker image](#-run-with-docker-http) — see\n[Choose how to run it](#-choose-how-to-run-it) below.\n\n## 🧭 Choose how to run it\n\n| | Setup | Best for |\n| ----------------------------------------------------------- | --------------------------------- | ----------------------------------------------------- |\n| 🌐 **[Hosted server](#-use-the-hosted-server-recommended)** | None — point your client at a URL | Most people: zero install, zero maintenance |\n| 💻 **[stdio via npx](#-install--run-with-stdio)** | `npx`, no build | Desktop MCP clients (Claude Desktop, Claude Code) |\n| 🐳 **[Docker (self-hosted HTTP)](#-run-with-docker-http)** | `docker run` | Running your own instance, on your own infrastructure |\n\n⬆️ [Back to top](#tartalomjegyzék)\n\n## 🌐 Use the hosted server (recommended)\n\nNo install, no self-hosting — point your MCP client at `https://mcp.billingo.hu` and\nsend your Billingo API key with every request. This is the fastest way to get started;\nreach for [stdio](#-install--run-with-stdio) or [Docker](#-run-with-docker-http) below only\nif you specifically need to self-host.\n\n### Claude Code CLI\n\n```bash\nclaude mcp add --transport http billingo https://mcp.billingo.hu \\\n -s user \\\n -H \"X-Billingo-Api-Key: your-api-key\" \\\n -H \"X-Billingo-Allow-Write: true\"\n```\n\n`-s user` registers it across every project instead of just the current one; use\n`-s local` (the default) to scope it to just this project. Drop the\n`X-Billingo-Allow-Write` header, or set it to `\"false\"`, for read-only access.\n\n### Other HTTP-capable MCP clients\n\nAny client that speaks Streamable HTTP works the same way: point it at\n`https://mcp.billingo.hu` with the `X-Billingo-Api-Key` header (required) and\noptionally `X-Billingo-Allow-Write` — see [Configuration](#-configuration) for the full\nheader reference.\n\nGet your API key the same way as described under [API key](#api-key) below.\n\n⬆️ [Back to top](#tartalomjegyzék)\n\n## 💻 Install / run with stdio\n\nNo install step — `npx` fetches and runs the package on demand.\n\n### Claude Desktop\n\n`claude_desktop_config.json`:\n\n```json\n{\n \"mcpServers\": {\n \"billingo\": {\n \"command\": \"npx\",\n \"args\": [\"-y\", \"@billingo/billingo-mcp\"],\n \"env\": {\n \"BILLINGO_API_KEY\": \"your-api-key\",\n \"BILLINGO_ALLOW_WRITE\": \"false\"\n }\n }\n }\n}\n```\n\n**Restart the client fully** afterwards — Claude Desktop reads this file only at startup,\nso quitting the window is not enough (use ⌘Q on macOS).\n\n### Claude Code CLI\n\n```bash\nclaude mcp add billingo -s user \\\n -e BILLINGO_API_KEY=your-api-key \\\n -e BILLINGO_ALLOW_WRITE=false \\\n -- npx -y @billingo/billingo-mcp\n```\n\n`-s user` registers the server for you across every project, not just the one you're\ncurrently in, without committing anything to a repo. Use `-s local` (the default)\ninstead to scope it to the current project only. Verify with `claude mcp list`, or\ninspect the saved config with `claude mcp get billingo`.\n\n### Other MCP clients\n\nAny client that accepts the standard `mcpServers` JSON shape (Cursor, Windsurf, and\nothers) can reuse the Claude Desktop block above as-is — `command`, `args`, and `env`\nare not Claude-specific, only the surrounding config file and its location differ.\n\n### API key\n\nGet your API key from Billingo under **Settings → API keys → New API key**. On the\ncreation form:\n\n- **Associated connection**: _Custom development_.\n- **API scope**: _Read_ if you only need to list or fetch data, or _Write_ if you also\n want to create, modify, send, or cancel documents.\n\nThis is a second, independent gate from `BILLINGO_ALLOW_WRITE` below: a Read-scoped key\nstill gets a permission error straight from the Billingo API on any write call, even if\n`BILLINGO_ALLOW_WRITE` is `\"true\"` here — both have to allow it. Leave\n`BILLINGO_ALLOW_WRITE` at `\"false\"` (or omit it) unless you actually want the model to\nbe able to create, modify, send, or cancel documents — see [Security](#-security). Note\nthat config files like `claude_desktop_config.json` are stored in plain text, so the key\nsits unencrypted on disk.\n\nTo check it worked: the client should list **22 tools** in read-only mode, or **49** with\n`BILLINGO_ALLOW_WRITE` set to `\"true\"`. If it reports no tools, check the client's log\n(on macOS, `~/Library/Logs/Claude/mcp-server-billingo.log`) — the server identifies\nitself as `{\"name\":\"billingo\",\"version\":\"0.1.0\"}`. A different name there means the\nclient is talking to some other server registered under the same name.\n\n⬆️ [Back to top](#tartalomjegyzék)\n\n## 🐳 Run with Docker (HTTP)\n\n```bash\ndocker run -p 3000:3000 ghcr.io/octonull/billingo-mcp:latest\n```\n\nThe image ships with **no API key baked in**. HTTP mode is stateless and per-request:\nevery call carries the Billingo API key in a header, and the server never stores it.\nExample call, showing the two Billingo-specific headers:\n\n```bash\ncurl -X POST http://localhost:3000 \\\n -H 'Content-Type: application/json' \\\n -H 'Accept: application/json, text/event-stream' \\\n -H 'X-Billingo-Api-Key: your-api-key' \\\n -H 'X-Billingo-Allow-Write: true' \\\n -d '{\"jsonrpc\":\"2.0\",\"id\":1,\"method\":\"tools/list\",\"params\":{}}'\n```\n\n`GET /health` returns `{\"status\":\"ok\"}` and needs no headers, for container health checks.\n`GET /build_version` returns the running image's build-time version, e.g.\n`{\"buildVer\":\"fcc756d@0.1.0\"}` — or just the commit SHA (`{\"buildVer\":\"fcc756d\"}`) if that\nbuild isn't from a release tag.\n\nGet the API key itself the same way as for stdio — see [API key](#api-key) above — and\ngive it Write scope on Billingo's side if you intend to send `X-Billingo-Allow-Write`.\n\n### Claude Code CLI\n\n```bash\nclaude mcp add --transport http billingo http://localhost:3000 \\\n -s user \\\n -H \"X-Billingo-Api-Key: your-api-key\" \\\n -H \"X-Billingo-Allow-Write: true\"\n```\n\n`-s user` registers it across every project instead of just the current one; use\n`-s local` (the default) to scope it to just this project. Drop the\n`X-Billingo-Allow-Write` header, or set it to `\"false\"`, for read-only access.\n\n⬆️ [Back to top](#tartalomjegyzék)\n\n## 🔧 Configuration\n\n| Variable | Transport | Required | Default | Meaning |\n| ------------------------ | ---------- | -------- | ---------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------- |\n| `BILLINGO_API_KEY` | stdio only | yes | — | Your Billingo API key. Not read in HTTP mode — see below. |\n| `BILLINGO_ALLOW_WRITE` | stdio only | no | `false` | `\"true\"` or `\"1\"` enables write tools for this stdio process. Any other value (including a typo) is treated as `false`. |\n| `BILLINGO_BASE_URL` | both | no | `https://api.billingo.hu/v3` | Override the API base URL, e.g. to point at a proxy. |\n| `PORT` | HTTP only | no | `3000` | Port the HTTP server listens on. |\n| `BILLINGO_ALLOWED_HOSTS` | HTTP only | no | unset (protection disabled) | Comma-separated list of `Host` header values the server will accept — DNS-rebinding protection. **Set this whenever the server is reachable from outside localhost.** |\n\nHTTP mode takes credentials and scope **per request**, as headers, instead:\n\n| Header | Required | Meaning |\n| ------------------------ | -------- | ------------------------------------------------------------ |\n| `X-Billingo-Api-Key` | yes | The Billingo API key to use for this request. Never stored. |\n| `X-Billingo-Allow-Write` | no | `\"true\"` or `\"1\"` enables write tools for this request only. |\n\n⬆️ [Back to top](#tartalomjegyzék)\n\n## 🔒 Security\n\nRead this section before exposing the server to anything.\n\n- **Read-only by default.** Write tools (create, update, delete, send, cancel) are\n filtered out of `tools/list` entirely unless `BILLINGO_ALLOW_WRITE` (stdio) or\n `X-Billingo-Allow-Write` (HTTP) is explicitly set. A model that never sees a write\n tool cannot call it. This is the primary safety mechanism — leave writes off unless\n you specifically need them.\n- **Issued invoices are reported to NAV automatically and cannot be undone.** Once a\n document is finalized into an invoice, Hungary's NAV Online Számla reporting happens\n immediately and is not reversible. The only remedy for a wrong invoice is a storno\n (cancellation) — and **a storno is itself irreversible**: it voids the invoice\n permanently and is also reported to NAV. There is no \"delete\" for an issued invoice.\n- **HTTP mode requires TLS.** The API key travels in the `X-Billingo-Api-Key` header on\n every request. Terminate TLS in front of the container (a reverse proxy, load\n balancer, or platform ingress) — never run HTTP mode over plain HTTP outside a\n trusted local network.\n- **HTTP mode stores no API key, by design.** Do not \"fix\" this by setting an API key\n via a container-wide environment variable — that turns the deployment single-tenant\n and lets **every caller who can reach the container bill your account**, since there\n would be nothing left to distinguish requests. The per-request header is the point.\n- **Set `BILLINGO_ALLOWED_HOSTS` whenever the HTTP server is exposed publicly.** Without\n it, DNS-rebinding protection is disabled.\n\n⬆️ [Back to top](#tartalomjegyzék)\n\n## 🧰 Tools\n\n49 tools total: 22 read (always visible), 27 write (visible only with writes enabled).\n\n**Organization** (3 read)\n\n- `billingo_get_organization` — Get organization details (tax code, subscription, NAV connection status).\n- `billingo_check_tax_number` — Validate a Hungarian tax number.\n- `billingo_get_conversion_rate` — Get an official currency conversion rate, optionally for a past date.\n\n**Partners** (2 read, 4 write)\n\n- `billingo_list_partners` — List partners.\n- `billingo_get_partner` — Get a single partner.\n- `billingo_create_partner` — Create a partner. _(write)_\n- `billingo_update_partner` — Update a partner (full replace). _(write)_\n- `billingo_guess_partner` — Find a partner by tax number/email, or create one. _(write)_\n- `billingo_delete_partner` — Delete a partner. _(write)_\n\n**Products** (3 read, 3 write)\n\n- `billingo_list_products` — List products.\n- `billingo_get_product` — Get a single product.\n- `billingo_get_product_quantity` — Get a product's stock quantity.\n- `billingo_create_product` — Create a product. _(write)_\n- `billingo_update_product` — Update a product (full replace). _(write)_\n- `billingo_delete_product` — Delete a product. _(write)_\n\n**Spendings** (2 read, 3 write)\n\n- `billingo_list_spendings` — List spendings.\n- `billingo_get_spending` — Get a single spending.\n- `billingo_create_spending` — Create a spending. _(write)_\n- `billingo_update_spending` — Update a spending (full replace). _(write)_\n- `billingo_delete_spending` — Delete a spending. _(write)_\n\n**Bank accounts** (2 read, 3 write)\n\n- `billingo_list_bank_accounts` — List bank accounts.\n- `billingo_get_bank_account` — Get a single bank account.\n- `billingo_create_bank_account` — Create a bank account. _(write)_\n- `billingo_update_bank_account` — Update a bank account (full replace). _(write)_\n- `billingo_delete_bank_account` — Delete a bank account. _(write)_\n\n**Document blocks** (1 read, 1 write)\n\n- `billingo_list_document_blocks` — List document blocks (invoice number ranges).\n- `billingo_create_document_block` — Create a document block. _(write)_\n\n**Documents — read** (8)\n\n- `billingo_list_documents` — List documents (invoices, receipts, proformas, drafts, and more).\n- `billingo_get_document` — Get a single document by id or vendor id.\n- `billingo_download_document` — Get the document PDF (public URL, or base64 bytes).\n- `billingo_get_document_public_url` — Get a shareable public URL for a document.\n- `billingo_get_online_szamla_status` — Get a document's NAV Online Számla reporting status. Errors when the document has no NAV record — e.g. the organization is not connected to NAV Online Számla, or the document isn't subject to reporting.\n- `billingo_get_document_payments` — Get the payments recorded against a document.\n- `billingo_get_document_reminders` — Get the reminder events sent for a document.\n- `billingo_pos_print` — Get a POS-thermal-printer-sized PDF receipt for a document.\n\n**Documents — write** (9)\n\n- `billingo_create_document` — Create a document (invoice, proforma, draft, or advance). _(write)_\n- `billingo_create_receipt` — Create a receipt. _(write)_\n- `billingo_finalize_draft` — Finalize a draft into an invoice — issues it and reports it to NAV. _(write)_\n- `billingo_finalize_receipt_draft` — Finalize a draft into a receipt. _(write)_\n- `billingo_create_document_from_proforma` — Create an invoice from a proforma. _(write)_\n- `billingo_copy_document` — Copy a document. _(write)_\n- `billingo_create_modification_document` — Create a modification (correction) document. _(write)_\n- `billingo_update_payment` — Update a document's recorded payments. _(write)_\n- `billingo_archive_document` — Archive a proforma document. _(write)_\n\n**Documents — export** (1 read)\n\n- `billingo_export_documents` — Export documents.\n\n**Documents — destructive** (4 write)\n\n- `billingo_cancel_document` — Cancel (storno) a document — irreversible. _(write)_\n- `billingo_send_document` — Send a document by email. _(write)_\n- `billingo_delete_document` — Delete a document (only drafts/unissued documents; an issued invoice must be cancelled instead). _(write)_\n- `billingo_delete_payment` — Delete a document's recorded payments. _(write)_\n\n⬆️ [Back to top](#tartalomjegyzék)\n\n## 🔨 Development\n\n```bash\ngit clone https://github.com/octonull/billingo-mcp.git\ncd billingo-mcp\nnpm ci\nnpm test\n```\n\n**TypeScript is pinned to 5.9.3** and cannot currently be upgraded: `openapi-typescript`\nrequires `typescript@^5.x`, and `typescript-eslint` requires `<6.1.0` — their\nintersection is 5.9.3. Installing a newer TypeScript fails `npm install` with an\n`ERESOLVE` conflict.\n\nOther useful commands: `npm run typecheck`, `npm run lint`, `npm run format`,\n`npm run test:coverage`, `npm run build`.\n\n**Live smoke suite:** `npm run test:live` runs a small suite against the real Billingo\nsandbox (creating and cleaning up real, if harmless, sandbox data). It needs\n`BILLINGO_SANDBOX_API_KEY` set to a sandbox API key; without it, the suite skips\ncleanly (this is also how CI and contributors without sandbox access run it safely).\n\n⬆️ [Back to top](#tartalomjegyzék)\n\n## 🤝 Contributing\n\nIssues and pull requests are welcome. Please run `npm run format:check`, `npm run lint`,\n`npm run typecheck`, and `npm run test:coverage` before opening a PR — CI enforces all\nfour. See [CLAUDE.md](CLAUDE.md) for the architecture and the constraints that aren't\nobvious from the code alone.\n\n⬆️ [Back to top](#tartalomjegyzék)\n\n## 📜 Licence\n\nMIT — see [LICENSE](LICENSE). Copyright (c) 2026 Billingo Technologies Zrt.\n\n⬆️ [Back to top](#tartalomjegyzék)\n","readmeFilename":"README.md"}