io.github.PromptPartner/bexio-mcp-server 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

Client	Transport	Status
Claude Desktop	stdio	✅ Fully supported
n8n	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
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
3. Enter your Bexio API token when prompted. It is stored in your operating system's keychain.
4. 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 <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

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

Variable	Required	Default	Description
BEXIO_API_TOKEN	Yes*	-	Your Bexio API token (single company)
BEXIO_API_TOKENS	Yes*	-	Multiple companies — see Multiple Companies
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:

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 <stdio|http>  Transport mode (default: stdio)
  --host <address>     HTTP host (default: 0.0.0.0)
  --port <number>      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

• Check your internet connection
• Verify BEXIO_BASE_URL is correct (default: https://api.bexio.com/2.0)

Payroll tools return "module not available"

• Payroll tools require the Bexio Payroll module subscription
• Contact Bexio support to enable the module

Claude Desktop doesn't see the server

• Quit Claude Desktop completely (not just the window) and restart it after configuration changes
• Check that it is connected: click + in the message box → Connectors → Manage connectors
• For the JSON config: check the file path for your OS and that the JSON is valid
• Check the logs: ~/Library/Logs/Claude/mcp-server-*.log (macOS) or %APPDATA%\Claude\logs (Windows)

Privacy Policy

This MCP server acts as a pass-through to the Bexio API and does not store any data. For full details, see our Privacy Policy.

Your data is processed according to Bexio's Privacy Policy.

Support

• Issues & Bug Reports: GitHub Issues
• Email: lukas@promptpartner.ai

Support the Project

If this project saves you time or helps your business, consider buying me a coffee! ☕

Your support helps keep this project maintained and improved!

Author

Created by Lukas Hertig from PromptPartner.ai

Acknowledgments

This project builds upon the original Bexio MCP server created by Sebastian Bryner of bryner.tech. His v1.0 implementation provided the foundational architecture and initial 83 tools that made this expanded v2.0 possible.

Development Tools

The expansion from 83 to 314 tools was developed using:

• GSD Framework - The "Get Shit Done" planning framework for structured AI-assisted development workflows

These tools helped transform a 4-weeks estimated project into a 2-days reality, demonstrating the potential of AI-augmented software development.

Disclaimer

This is an independent, community-driven project and is not affiliated with, endorsed by, or officially connected to Bexio AG in any way. "Bexio" is a trademark of Bexio AG. This project simply provides an integration layer to the publicly available Bexio API.

Use of this software is at your own risk. The authors are not responsible for any issues arising from its use with your Bexio account.

License

MIT - See LICENSE for details.

Star History

<a href="https://www.star-history.com/?repos=promptpartner%2Fbexio-mcp-server&type=date&legend=top-left"> <picture> <source media="(prefers-color-scheme: dark)" srcset="https://api.star-history.com/chart?repos=promptpartner/bexio-mcp-server&type=date&theme=dark&legend=top-left" /> <source media="(prefers-color-scheme: light)" srcset="https://api.star-history.com/chart?repos=promptpartner/bexio-mcp-server&type=date&legend=top-left" /> <img alt="Star History Chart" src="https://api.star-history.com/chart?repos=promptpartner/bexio-mcp-server&type=date&legend=top-left" /> </picture> </a>

Links

• Bexio API Documentation
• MCP Protocol Specification
• PromptPartner.ai