bexio MCP Server

English · Deutsch

A standalone Model Context Protocol (MCP) server for the bexio REST API. Usable from any MCP client — Claude Desktop, Claude Code, n8n and others.

The server depends on nothing but a bexio API token. No database, no framework, no host application.

Transports

Transport	For	Enable
stdio (default)	Claude Desktop, Claude Code, CLI clients	MCP_TRANSPORT=stdio (default)
HTTP (Streamable HTTP)	n8n, remote clients, Docker	MCP_TRANSPORT=http or arg http

Available tools (21)

Tool	Description
bexio_list_contacts / _invoices / _quotes / _orders / _items / _projects	List with pagination (limit, offset, order_by)
bexio_get_contact / _invoice / _quote / _order / _item / _project	Single record by id
bexio_search_contacts / _invoices / _quotes / _orders / _items / _projects	Search with field criteria (POST /search)
bexio_get_company_profile	Company profile of the account
bexio_create_contact	Create a contact (company or person)
bexio_request	Generic call for any bexio endpoint

bexio_request reaches every endpoint of the API (e.g. /3.0/banking/accounts, /2.0/taxes, /2.0/kb_invoice/{id}/payment) and thus covers the entire API surface.

Example: search

{
  "criteria": [{ "field": "name_1", "value": "Muster", "criteria": "like" }],
  "limit": 50
}

Operators: =, !=, >, <, >=, <=, like, not_like, is_null, not_null, in, not_in.

Installation

cd bexio-mcp
npm install
npm run build
cp .env.example .env   # set BEXIO_API_TOKEN

Create a token: bexio → Settings → API & Webhooks → API tokens. The token's scope determines which resources are readable/writable (e.g. contact_show, kb_invoice_show).

---

Claude Desktop (stdio)

claude_desktop_config.json (macOS: ~/Library/Application Support/Claude/claude_desktop_config.json):

{
  "mcpServers": {
    "bexio": {
      "command": "node",
      "args": ["/absolute/path/bexio-mcp/dist/index.js"],
      "env": { "BEXIO_API_TOKEN": "your-token-here" }
    }
  }
}

Claude Code (stdio)

claude mcp add bexio --env BEXIO_API_TOKEN=your-token -- node /absolute/path/bexio-mcp/dist/index.js

---

n8n (HTTP)

n8n speaks MCP over HTTP. Start the server in HTTP mode — easiest via Docker:

# fill .env with BEXIO_API_TOKEN and MCP_HTTP_TOKEN, then:
docker compose up -d --build

Or without Docker:

MCP_TRANSPORT=http MCP_HTTP_TOKEN=secret BEXIO_API_TOKEN=... node dist/index.js

In the n8n workflow, add the "MCP Client Tool" node:

• Endpoint / SSE URL: http://<host>:3000/mcp (when n8n is on the same Docker network, e.g. http://bexio-mcp:3000/mcp)
• Transport: HTTP Streamable
• Authentication / Header: Authorization: Bearer secret (value of MCP_HTTP_TOKEN)

Liveness check: GET http://<host>:3000/health → {"status":"ok"}.

Manual test of the HTTP endpoint

curl -X POST http://localhost:3000/mcp \
  -H 'Authorization: Bearer secret' \
  -H 'Content-Type: application/json' \
  -H 'Accept: application/json, text/event-stream' \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/list","params":{}}'

---

Environment variables

Variable	Default	Purpose
BEXIO_API_TOKEN	— (required)	bexio PAT or OAuth2 access token
BEXIO_API_BASE_URL	https://api.bexio.com	API base URL
MCP_TRANSPORT	stdio	stdio or http
MCP_HTTP_PORT / PORT	3000	Port in HTTP mode
MCP_HTTP_HOST	0.0.0.0	Bind host in HTTP mode
MCP_HTTP_TOKEN	—	If set: required bearer token for /mcp

Development

npm run watch     # TypeScript watch mode
npm run inspect   # MCP Inspector (interactive tool testing)

Security

• The bexio token grants full API access within its scopes — never commit it (.env and dist/ are in .gitignore).
• In HTTP mode always set MCP_HTTP_TOKEN when the port is reachable. Without it, /mcp is open — and so is your bexio account.

Privacy

This server stores no data. It forwards requests unchanged to the bexio REST API and returns the responses to the MCP client. There is no database, no logging of payload data, and no sharing with third parties. Processing of your bexio data is governed solely by bexio's privacy policy.

License

Released under the MIT License. © 2026 Valmir Emini.

Disclaimer & trademarks

This is an unofficial, independent open-source project. It is not affiliated with, endorsed by, sponsored by, or approved by bexio AG.

"bexio" is a trademark of bexio AG. All trademark and product names are the property of their respective owners and are used here solely for identification purposes.

The software is provided "as is", without warranty of any kind (see LICENSE). Use of the bexio API is at your own risk and subject to bexio AG's terms of use. The author accepts no liability for any damage or data loss arising from the use of this server.