billingo-mcp

billingo-mcp


MCP server for the Billingo V3 Hungarian invoicing API. Manage invoices, partners, products, spendings, and bank accounts from any MCP client.

Quick Start

1. Get your API key from Billingo API settings

1. Add to your Claude Code settings (~/.claude/settings.json) or Claude Desktop config:

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

1. Restart Claude and start managing your invoices.

Configuration

| Environment Variable | Required | Default | Description | |---------------------|----------|---------|-------------| | BILLINGO_API_KEY | Yes | -- | Your Billingo API key | | BILLINGO_MOCK | No | false | Set to true for mock mode (no API calls) |

Mock mode is activated automatically when no API key is provided, or explicitly with BILLINGO_MOCK=true. Useful for development and testing.

Tools

Documents

| Tool | Description | |------|-------------| | list_documents | List invoices with filters (partner, status, date range, type, payment method) | | create_document | Create invoices, proformas, advance invoices, or drafts | | get_document | Get document details by ID | | cancel_document | Cancel (storno) a document | | send_document | Send document via email | | download_document | Download document as PDF | | get_document_public_url | Get public URL for a document | | update_payment | Record or update payment on a document |

Partners

| Tool | Description | |------|-------------| | list_partners | List partners with search | | create_partner | Create a new partner (with address, tax info) | | get_partner | Get partner details by ID | | update_partner | Update an existing partner |

Products

| Tool | Description | |------|-------------| | list_products | List products | | create_product | Create a new product | | get_product | Get product details by ID | | update_product | Update an existing product |

Spendings

| Tool | Description | |------|-------------| | list_spending | List spendings with filters | | create_spending | Create a spending entry (with line items and VAT) | | get_spending | Get spending details by ID |

Bank Accounts

| Tool | Description | |------|-------------| | list_bank_accounts | List bank accounts | | create_bank_account | Create a new bank account | | get_bank_account | Get bank account details by ID | | update_bank_account | Update an existing bank account |

Utilities

| Tool | Description | |------|-------------| | check_tax_number | Validate a Hungarian tax number via NAV | | get_organization | Get your own organization data | | get_currency_rates | Get exchange rates | | list_document_blocks | List invoice numbering sequences |

Development

git clone https://github.com/bartadaniel/billingo-mcp.git
cd billingo-mcp
npm install
npm run build

Use the local build in your config:

{
  "mcpServers": {
    "billingo": {
      "command": "node",
      "args": ["path/to/billingo-mcp/bin/billingo-mcp.js"],
      "env": {
        "BILLINGO_API_KEY": "your-api-key"
      }
    }
  }
}

Mock Mode

Run without an API key for development:

npm run dev

This starts the server with BILLINGO_MOCK=true, returning realistic fixture data for all tools.

License

MIT