Bexio MCP Server

@promptpartner/bexio-mcp-server

Complete Swiss accounting integration for Bexio via the Model Context Protocol (MCP). 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 you find!

Compatibility

Quick Start

For Claude Desktop

Option A: MCPB Bundle (Easiest)

1. Download the latest .mcpb file from GitHub Releases
2. Install it in Claude Desktop, either way works:

• Double-click the .mcpb file (or drag it onto the Claude Desktop window), or
• go to Settings → Extensions → Advanced settings, and under Extension Developer click Install Extension… and select the file

1. Enter your Bexio API token when prompted. It is stored in your operating system's keychain.
2. Optional: switch on Interactive panels in the extension's settings for invoice previews, contact cards and a dashboard.

No Node.js installation is needed: Claude Desktop runs extensions with its built-in Node.js. Updating from 2.6.1 or older? Re-enter your token if Claude Desktop asks for it.

Option B: npm (manual config)

Requires Node.js (LTS). In Claude Desktop, open Settings → Developer → Edit Config and add:

{

"mcpServers": { "bexio": { "command": "npx", "args": ["-y", "@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

Then quit Claude Desktop completely and restart it. Note that this file keeps your token in plain text; the extension (Option A) stores it in the keychain instead.

For n8n and Other HTTP Clients

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

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

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

Or build from source:

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

\* 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:

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 (defaults to the first):

{

"mcpServers": { "bexio": { "command": "npx", "args": ["@promptpartner/bexio-mcp-server"], "env": { "BEXIO_API_TOKENS": "Acme:token-for-acme,Globex:token-for-globex", "BEXIO_DEFAULT_COMPANY": "Acme" } } } }

Then just ask Claude things like *"switch to Globex and show this month's invoices."* list_companies shows the configured companies and which one is active; in multi-company mode each response also notes the active_company so it's always clear which company a result came from. Tokens are never logged or returned. The two control tools appear only when BEXIO_API_TOKENS is set, so single-company setups are unchanged.

HTTP/n8n note: the active company is process-global. For concurrent multi-tenant

HTTP deployments, run one instance per company instead.

Command Line Options

npx @promptpartner/bexio-mcp-server [options]

Options: --mode Transport mode (default: stdio) --host HTTP host (default: 0.0.0.0) --port HTTP port (default: 8000)

Troubleshooting

"Invalid API token" error

• Verify your token at developer.bexio.com > Personal Access Tokens
• Ensure the token has not expired
• Check that the token has the required permissions

"Connection refused" error

• Che