# billingo-mcp

[![npm](https://img.shields.io/npm/v/@daniel.barta/billingo-mcp)](https://www.npmjs.com/package/@daniel.barta/billingo-mcp)

MCP server for the [Billingo](https://www.billingo.hu) 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](https://app.billingo.hu/api-key)

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

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

3. 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

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

Use the local build in your config:

```json
{
  "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:

```bash
npm run dev
```

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

## License

MIT