# bexio MCP Server

**English** · [Deutsch](README.de.md)

A **standalone** [Model Context Protocol](https://modelcontextprotocol.io/) (MCP)
server for the [bexio REST API](https://docs.bexio.com/). 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

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

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

## Installation

```bash
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`):

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

## Claude Code (stdio)

```bash
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:

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

Or without Docker:

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

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

```bash
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](https://www.bexio.com/de-CH/datenschutz).

## License

Released under the [MIT License](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](LICENSE)).
Use of the bexio API is at your own risk and subject to
[bexio AG's terms of use](https://www.bexio.com/). The author accepts no liability for any
damage or data loss arising from the use of this server.