bexio-mcp-server

# @promptpartner/bexio-mcp-server

Complete Swiss accounting integration for [Bexio](https://www.bexio.com/) via the [Model Context Protocol (MCP)](https://modelcontextprotocol.io/). Works with **Claude Desktop**, **n8n**, and any MCP-compatible client.

Manage invoices, contacts, projects, time tracking, and 300+ more tools through AI conversation or workflow automation.

> ⚠️ **Early Release Software**
>
> This project is under active development. While it's functional and tested, you may encounter bugs or unexpected behavior. Features will continue to be added and improved over time. Please [report any issues](https://github.com/promptpartner/bexio-mcp-server/issues) you find!

## Compatibility

| Client | Transport | Status |
|--------|-----------|--------|
| [Claude Desktop](https://claude.ai/download) | stdio | ✅ Fully supported |
| [n8n](https://n8n.io/) | HTTP | ✅ Fully supported |
| Other MCP clients | stdio/HTTP | ✅ Should work |

## Quick Start

### For Claude Desktop

**Option A: MCPB Bundle (Easiest)**

1. Download the latest `.mcpb` file from [GitHub Releases](https://github.com/promptpartner/bexio-mcp-server/releases/latest)
2. In Claude Desktop, go to **Settings → Extensions**
3. Install the extension using one of these methods:
   - **Double-click** the downloaded `.mcpb` file, or
   - **Drag and drop** the file onto the Extensions window, or
   - Click **Advanced Settings → Install Extension** and select the file
4. Enter your Bexio API token when prompted

**Option B: npm**

Add to `claude_desktop_config.json`:

```json
{
  "mcpServers": {
    "bexio": {
      "command": "npx",
      "args": ["@promptpartner/bexio-mcp-server"],
      "env": {
        "BEXIO_API_TOKEN": "your-token-here"
      }
    }
  }
}
```

Config location:
- **macOS:** `~/Library/Application Support/Claude/claude_desktop_config.json`
- **Windows:** `%APPDATA%\Claude\claude_desktop_config.json`

### For n8n and Other HTTP Clients

Start the server in HTTP mode, with a bearer token:

```bash
BEXIO_API_TOKEN=your-token BEXIO_HTTP_TOKEN=$(openssl rand -hex 32) \
  npx @promptpartner/bexio-mcp-server --mode http --host 127.0.0.1 --port 8000
```

Clients then send `Authorization: Bearer <BEXIO_HTTP_TOKEN>` on every request (`GET /`,
the health check, stays open).

> **Security:** every tool reads or changes your books. Without `BEXIO_HTTP_TOKEN` the HTTP
> endpoints are unauthenticated: on `0.0.0.0` (the default) anyone who can reach the port
> can use them, and because CORS allows any origin, even a loopback-only server can be
> called by a web page open in your browser. The server warns at startup when no token is
> set. Local file paths (`upload_file` `file_path`, `download_file` `output_path`) are
> refused over HTTP unless `BEXIO_FILE_DIR` names a directory to confine them to.

The server exposes MCP over HTTP at `http://localhost:8000`. Configure your MCP client to connect to this endpoint.

### For Other stdio Clients

```bash
BEXIO_API_TOKEN=your-token npx @promptpartner/bexio-mcp-server
```

Or build from source:

```bash
git clone https://github.com/promptpartner/bexio-mcp-server
cd bexio-mcp-server/src
npm install && npm run build
BEXIO_API_TOKEN=your-token node dist/index.js
```

## Getting Your Bexio API Token

1. Go to [developer.bexio.com](https://developer.bexio.com/)
2. Log in with your regular Bexio account
3. Navigate to **Personal Access Tokens**
4. Click **Create New Token**
5. Copy the token and use it in your configuration

## Features

This MCP server provides **315 tools** across all Bexio domains:

### Contacts & CRM
- Create, update, search contacts
- Contact groups, sectors, salutations, titles
- Contact relations management

### Invoices & Sales
- Full invoice lifecycle (create, issue, send, cancel)
- Quotes with accept/decline workflows
- Orders with delivery management
- Incoming payments tracking
- Interactive invoice preview (Claude Desktop)

### Banking & Payments
- Swiss QR-bill payment support (QR-IBAN)
- Standard IBAN payments (ISO 20022)
- Currency management (CHF, EUR)
- Bank account management

### Projects & Time Tracking
- Project management with types and statuses
- Milestones and work packages
- Timesheet entries with duration tracking
- Business activities and communication types

### Accounting
- Chart of accounts
- Manual journal entries, incl. group entries (Sammelbuchung: one voucher, many postings)
- Journal by date range and account; computed account balances (Saldenliste)
- Business years and VAT periods
- Account groups

### Purchase & Expenses
- Bills (creditor invoices)
- Expenses and purchase orders
- Outgoing payments

### Files & Documents
- Document upload/download; upload straight from a local file path (no base64 through the chat)
- File management

### Payroll (requires Bexio Payroll module)
- Employee management
- Absence tracking
- Payroll documents

## Examples

Here are some real-world examples of using the Bexio MCP server with Claude:

### Example 1: Finding Overdue Invoices

**Prompt:**
> "Show me all overdue invoices"

**What happens:**
Claude uses the `get_overdue_invoices` tool to query Bexio for all invoices past their due date.

**Response:**
> Found 3 overdue invoices:
>
> | Invoice # | Customer | Amount | Due Date | Days Overdue |
> |-----------|----------|--------|----------|--------------|
> | INV-2024-001 | Acme AG | CHF 2,450.00 | 2024-01-15 | 18 days |
> | INV-2024-003 | Tech GmbH | CHF 890.50 | 2024-01-20 | 13 days |
> | INV-2024-007 | Swiss Corp | CHF 5,200.00 | 2024-01-25 | 8 days |
>
> Total overdue: CHF 8,540.50

---

### Example 2: Creating an Invoice

**Prompt:**
> "Create an invoice for contact 'Sunrise AG' with two items: 10 hours of consulting at CHF 150/hour and a software license for CHF 500"

**What happens:**
Claude uses `find_contact_by_name` to locate the customer, then `create_invoice` with the specified line items.

**Response:**
> Created Invoice INV-2024-015 for Sunrise AG:
>
> - 10x Consulting Hours @ CHF 150.00 = CHF 1,500.00
> - 1x Software License @ CHF 500.00 = CHF 500.00
>
> Subtotal: CHF 2,000.00
> VAT (8.1%): CHF 162.00
> **Total: CHF 2,162.00**
>
> Invoice is in draft status. Say "issue invoice INV-2024-015" to finalize it.

---

### Example 3: Project Time Summary

**Prompt:**
> "How much time was logged on project 'Website Redesign' this month?"

**What happens:**
Claude uses `search_projects` to find the project, then `search_timesheets` to get time entries filtered by project and date range.

**Response:**
> Time logged on "Website Redesign" (January 2024):
>
> | Team Member | Hours | Activities |
> |-------------|-------|------------|
> | Anna M. | 24:30 | Design, Meetings |
> | Marco K. | 18:15 | Development |
> | Lisa B. | 8:00 | Content Writing |
>
> **Total: 50 hours 45 minutes**
>
> Budget used: 50.75 of 80 hours (63%)

---

### Example 4: Customer Revenue Report

**Prompt:**
> "What's my revenue from 'Tech Solutions GmbH' this year?"

**What happens:**
Claude uses `find_contact_by_name` to identify the customer, then `get_customer_revenue_report` to calculate total revenue from paid invoices.

**Response:**
> Revenue from Tech Solutions GmbH (2024):
>
> - Q1: CHF 12,450.00 (3 invoices)
> - Q2: CHF 8,200.00 (2 invoices)
> - Q3: CHF 15,800.00 (4 invoices)
> - Q4: CHF 6,500.00 (2 invoices, 1 pending)
>
> **Total paid: CHF 42,950.00**
> **Pending: CHF 3,200.00**

## Environment Variables

| Variable | Required | Default | Description |
|----------|----------|---------|-------------|
| `BEXIO_API_TOKEN` | Yes* | - | Your Bexio API token (single company) |
| `BEXIO_API_TOKENS` | Yes* | - | Multiple companies — see [Multiple Companies](#multiple-companies-mandates) |
| `BEXIO_DEFAULT_COMPANY` | No | first | Which company is active at startup |
| `BEXIO_BASE_URL` | No | `https://api.bexio.com/2.0` | API endpoint URL |
| `BEXIO_ENABLED_CATEGORIES` | No | (all) | Comma-separated tool-category whitelist — see below |
| `BEXIO_HTTP_TOKEN` | Recommended for HTTP | - | Bearer token required on every HTTP endpoint except `GET /` |
| `BEXIO_FILE_DIR` | No | - | Directory that `upload_file` `file_path` / `download_file` `output_path` are confined to. Required for local paths over HTTP; optional extra confinement over stdio |
| `BEXIO_DOWNLOAD_INLINE_MAX_BYTES` | No | `64000` | `download_file` returns files up to this size inline as base64; larger ones are written to disk |

\* Provide either `BEXIO_API_TOKEN` (one company) or `BEXIO_API_TOKENS` (several).

### Reducing Token Budget — Category Whitelist

All tools are registered by default. For focused workflows or smaller models,
registering only a subset reduces the system-prompt token cost. Set
`BEXIO_ENABLED_CATEGORIES` to a comma-separated list:

```bash
BEXIO_ENABLED_CATEGORIES=contacts,invoices,purchase,banking,quotes,projects
```

Available categories: `reference`, `company`, `banking`, `projects`,
`timetracking`, `accounting`, `purchase`, `files`, `payroll`, `contacts`,
`invoices`, `orders`, `quotes`, `payments`, `reminders`, `deliveries`,
`items`, `reports`, `users`, `misc`, `notes`, `tasks`, `stock`, `docs`,
`positions`. Unknown names are ignored (logged to stderr); empty/unset = all
enabled (backward compatible).

## Multiple Companies (Mandates)

Bexio binds each API token to a **single company (mandate)** — there is no token that
spans companies. To work with several companies, generate one token per company (switch
to that company in Bexio first, then Settings → API Tokens), and configure them all on a
**single** server instance. Two new tools — `list_companies` and `select_company` — let
you switch the active company in conversation ("in Globex, list open invoices"). This
avoids running one server per company and the duplicated tool-context that comes with it.

Set `BEXIO_API_TOKENS` instead of (or alongside) `BEXIO_API_TOKEN`, as a comma-separated
list of `label:token` pairs (or a JSON object). `BEXIO_DEFAULT_COMPANY` picks the company
active at startup (de