billingo-mcp

<p align="center"><a href="https://billingo.hu" target="_blank"><img src="https://app.billingo.hu/v3/images_accelerate/billingo-logo-2025.svg" width="250"></a></p> <p align="center"> <a href="https://github.com/octonull/billingo-mcp/actions/workflows/ci.yml"><img src="https://img.shields.io/github/actions/workflow/status/octonull/billingo-mcp/ci.yml?branch=master&label=CI&logo=github" alt="CI"></a> <!-- No CodeQL badge: that workflow is workflow_dispatch-only (manual), so a status badge for it wouldn't reflect an ongoing, automatic signal — it'd just show whenever someone last ran it by hand. --> <a href="https://www.npmjs.com/package/@billingo/billingo-mcp"><img src="https://img.shields.io/npm/v/@billingo/billingo-mcp?logo=npm&label=npm" alt="npm version"></a> <a href="https://github.com/octonull/billingo-mcp/pkgs/container/billingo-mcp"><img src="https://img.shields.io/badge/ghcr.io-image-blue?logo=docker&logoColor=white" alt="Docker image on ghcr.io"></a> <a href="LICENSE"><img src="https://img.shields.io/badge/licence-MIT-blue" alt="Licence: MIT"></a> <br> <a href="#-telepítés--futtatás-stdio-val"><img src="https://img.shields.io/badge/node-%3E%3D22-5FA04E?logo=node.js&logoColor=white" alt="Node >=22"></a> <a href="#-fejlesztés"><img src="https://img.shields.io/badge/TypeScript-5.9.3%20(pinned)-3178C6?logo=typescript&logoColor=white" alt="TypeScript 5.9.3, pinned"></a> <a href="https://modelcontextprotocol.io"><img src="https://img.shields.io/badge/MCP-stdio%20%2B%20HTTP-234232" alt="MCP: stdio and Streamable HTTP"></a> <br> <a href="#-eszközök"><img src="https://img.shields.io/badge/tools-22%20read%20%2F%2027%20write-blue" alt="49 tools: 22 read, 27 write"></a> <a href="#-biztonság"><img src="https://img.shields.io/badge/default-read--only-success" alt="Read-only by default"></a> </p> <p align="center">🇭🇺 Magyarul · <a href="#english">🇬🇧 English</a></p>

A hivatalos Billingo MCP szerver — 49 eszköz (tool) a Billingo v3 számlázási API felett, stdio (asztali) és Streamable HTTP (önállóan üzemeltethető) kliensekhez. MIT licenc alatt, önállóan üzemeltethető. Ez az első hivatalos Billingo SDK vagy MCP szerver — korábban nem létezett ilyen.

A legtöbb felhasználónak nincs szükség telepítésre — használd a hosztolt szervert a mcp.billingo.hu címen. Inkább saját magad futtatnád? Publikálva van npm-en is @billingo/billingo-mcp néven (npx, build nélkül), és Docker image formájában is — lásd a Válassz futtatási módot szakaszt lentebb.

Olvasd angolul is — az angol szakasz egy teljes fordítás, nem összefoglaló.

Tartalomjegyzék

• 🧭 Válassz futtatási módot
• 🌐 Használat a hosztolt szerverrel
• 💻 Telepítés / futtatás stdio-val
• 🐳 Futtatás Dockerrel (HTTP)
• 🔧 Konfiguráció
• 🔒 Biztonság
• 🧰 Eszközök
• 🔨 Fejlesztés
• 🤝 Közreműködés
• 📜 Licenc
• 🇬🇧 English

🧭 Válassz futtatási módot

| | Beállítás | Kinek ajánlott | | --------------------------------------------------------------------- | ------------------------------------------- | ------------------------------------------------------------- | | 🌐 Hosztolt szerver | Semmi — csak add meg a kliensedben az URL-t | A legtöbb felhasználónak: nulla telepítés, nulla karbantartás | | 💻 stdio npx-szel | npx, build nélkül | Asztali MCP kliensek (Claude Desktop, Claude Code) | | 🐳 Docker (önálló üzemeltetés, HTTP) | docker run | Ha saját infrastruktúrán akarod futtatni |

⬆️ Ugrás az elejére

🌐 Használat a hosztolt szerverrel (ajánlott)

Nincs telepítés, nincs önálló üzemeltetés — csak állítsd be a klienst a https://mcp.billingo.hu címre, és minden kéréssel küldd el a Billingo API kulcsodat. Ez a leggyorsabb módja a kezdésnek; csak akkor nyúlj a stdio vagy Docker módokhoz lentebb, ha kifejezetten önálló üzemeltetésre van szükséged.

Claude Code CLI

claude mcp add --transport http billingo https://mcp.billingo.hu \
  -s user \
  -H "X-Billingo-Api-Key: your-api-key" \
  -H "X-Billingo-Allow-Write: true"

A -s user az összes projekteden át regisztrálja, nem csak az aktuálisban; az (alapértelmezett) -s local-lal csak az aktuális projektre korlátozod. Hagyd el az X-Billingo-Allow-Write fejlécet, vagy állítsd "false"-ra, csak-olvasás hozzáféréshez.

Más HTTP-kompatibilis MCP kliensek

Bármelyik kliens, amely támogatja a Streamable HTTP protokollt, ugyanígy működik: állítsd be rá a https://mcp.billingo.hu címet, az X-Billingo-Api-Key fejléccel (kötelező), opcionálisan az X-Billingo-Allow-Write-tal — a teljes fejléc-referenciáért lásd a Konfiguráció szakaszt.

Az API kulcsot ugyanúgy szerezd be, mint az API kulcs szakaszban lentebb leírtak szerint.

⬆️ Ugrás az elejére

💻 Telepítés / futtatás stdio-val

Nincs telepítési lépés — az npx igény szerint letölti és futtatja a csomagot.

Claude Desktop

claude_desktop_config.json:

{
  "mcpServers": {
    "billingo": {
      "command": "npx",
      "args": ["-y", "@billingo/billingo-mcp"],
      "env": {
        "BILLINGO_API_KEY": "your-api-key",
        "BILLINGO_ALLOW_WRITE": "false"
      }
    }
  }
}

Utána indítsd újra teljesen a klienst — a Claude Desktop csak induláskor olvassa ezt a fájlt, tehát az ablak bezárása nem elég (macOS-en ⌘Q).

Claude Code CLI

claude mcp add billingo -s user \
  -e BILLINGO_API_KEY=your-api-key \
  -e BILLINGO_ALLOW_WRITE=false \
  -- npx -y @billingo/billingo-mcp

A -s user a felhasználódhoz köti a szervert az összes projekteden át, nem csak az aktuálishoz, és semmit nem ír a repóba. Az (alapértelmezett) -s local-lal csak az aktuális projektre korlátozod. Ellenőrzés: claude mcp list, illetve a mentett konfiguráció megtekintése: claude mcp get billingo.

Más MCP kliensek

Bármelyik kliens, amely elfogadja a szabványos mcpServers JSON formátumot (pl. Cursor, Windsurf), változtatás nélkül újrahasznosíthatja a fenti Claude Desktop blokkot — a command, args és env nem Claude-specifikus, csak a befoglaló konfigurációs fájl és annak helye tér el klienstől függően.

API kulcs

Az API kulcsot a Billingóban a Beállítások → API kulcsok → Új API kulcs menüpont alatt hozod létre. Az űrlapon:

• Hozzátartozó összekötés: Egyedi fejlesztés.
• API hatásköre: Olvasás, ha csak listázni/lekérdezni akarsz, vagy Írás, ha dokumentumokat is szeretnél létrehozni, módosítani, küldeni vagy stornózni.

Ez egy második, a lenti BILLINGO_ALLOW_WRITE-tól független kapu: egy csak-olvasás hatáskörű kulcs minden író hívásnál közvetlenül a Billingo API-tól kap jogosultsági hibát, még akkor is, ha itt a BILLINGO_ALLOW_WRITE "true"-ra van állítva — mindkettőnek engedélyeznie kell. Hagyd a BILLINGO_ALLOW_WRITE-ot "false"-on (vagy hagyd el), hacsak nem szeretnéd, hogy a modell dokumentumokat hozhasson létre, módosíthasson, küldhessen el vagy storno­zhasson — lásd a Biztonság szakaszt. Fontos: az olyan konfigurációs fájlok, mint a claude_desktop_config.json, sima szövegként tárolódnak, tehát a kulcs titkosítatlanul áll a lemezen.

Ellenőrzés: a kliensnek read-only módban 22 eszközt kell listáznia, "true"-ra állított BILLINGO_ALLOW_WRITE mellett pedig 49-et. Ha nem talál eszközt, nézd meg a kliens naplóját (macOS-en ~/Library/Logs/Claude/mcp-server-billingo.log) — a szerver {"name":"billingo","version":"0.1.0"} néven mutatkozik be. Ha ott más név szerepel, akkor a kliens egy másik, ugyanezen a néven regisztrált szerverhez beszél.

⬆️ Ugrás az elejére

🐳 Futtatás Dockerrel (HTTP)

docker run -p 3000:3000 ghcr.io/octonull/billingo-mcp:latest

A image nem tartalmaz beégetett API kulcsot. A HTTP mód állapotmentes (stateless) és kérésenkénti: minden hívás egy fejlécben (header) viszi a Billingo API kulcsot, a szerver soha nem tárolja azt. Példahívás, a két Billingo-specifikus fejléccel:

curl -X POST http://localhost:3000 \
  -H 'Content-Type: application/json' \
  -H 'Accept: application/json, text/event-stream' \
  -H 'X-Billingo-Api-Key: your-api-key' \
  -H 'X-Billingo-Allow-Write: true' \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/list","params":{}}'

A GET /health {"status":"ok"}-kal válaszol, fejléc nélkül is — ez a konténer health checkekhez van. A GET /build_version a futó image build-idejű verzióját adja vissza, pl. {"buildVer":"fcc756d@0.1.0"} — vagy csak a commit SHA-t ({"buildVer":"fcc756d"}), ha az adott build nem tartozik release tag-hez.

Magát az API kulcsot ugyanúgy hozd létre, mint stdio-nál — lásd az API kulcs szakaszt fentebb —, és adj neki Írás hatáskört a Billingo oldalán, ha küldeni akarod az X-Billingo-Allow-Write fejlécet.

Claude Code CLI

claude mcp add --transport http billingo http://localhost:3000 \
  -s user \
  -H "X-Billingo-Api-Key: your-api-key" \
  -H "X-Billingo-Allow-Write: true"

A -s user itt is az összes projekteden át regisztrálja, nem csak az aktuálisban; az (alapértelmezett) -s local-lal csak az aktuális projektre korlátozod. Hagyd el az X-Billingo-Allow-Write fejlécet, vagy állítsd "false"-ra, csak-olvasás hozzáféréshez.

⬆️ Ugrás az elejére

🔧 Konfiguráció

| Változó | Transport | Kötelező | Alapérték | Jelentés | | -------------------------- | ---------- | -------- | ------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | BILLINGO_API_KEY | csak stdio | igen | — | A Billingo API kulcsod. HTTP módban nem ezt olvassa a szerver — lásd lent. | | 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. | | BILLINGO_TOOL_CATEGORIES | csak stdio | nem | mind | Vesszővel elválasztott eszközcsoportok, csak ezek töltődnek be: organization, partners, products, spendings, bank_accounts, document_blocks, documents. Ismeretlen név esetén a szerver el sem indul. | | 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.