@aiwerk/mcp-server-bexio

MCP server for the bexio API, the Swiss business software for invoicing, accounting, CRM, projects and payroll.

310 tools covering the complete public API surface across all three API versions, generated from bexio's official OpenAPI 3.0.2 specification.

Contacts        Quotes        Invoices       Bills          Projects
Orders          Deliveries    Payments       Expenses       Timesheets
Items           Reminders     Banking        Payroll        Files
Accounting      Taxes         Currencies     Users          Notes

Why generated

Every endpoint, HTTP verb, parameter and field name comes from the official specification rather than from prose documentation. Hand written API clients drift: they call routes that do not exist, use the wrong verb, target the wrong API version, or advertise fields the server rejects. None of that can be introduced here, because none of it is written by hand.

What a specification cannot tell you are the business rules, so the write paths are also exercised against a live account. See Testing.

Install

npm install -g @aiwerk/mcp-server-bexio

Requires Node.js 18 or newer.

Authentication

There are two ways in, and which one is appropriate depends on whose account it is.

OAuth 2.0, for an account you do not own

bexio runs its identity layer on Keycloak with PKCE and refresh tokens. Signing in grants only the permissions the integration asks for, and the authorisation does not expire on a fixed schedule.

This is the only appropriate route for a client's account. It is available through the AIWerk hosted service, which owns the authorisation flow and the token lifecycle and passes the access token to the server in BEXIO_API_TOKEN. Running the server standalone with your own OAuth client is possible, but you have to refresh the token yourself.

Personal access token, for your own account

Create one at developer.bexio.com/pat.

export BEXIO_API_TOKEN="your-token"

Two things to know:

• It is valid for 60 days and cannot be renewed, only replaced.
• It carries every scope, so it grants full access to the company data. bexio documents personal access tokens as strictly personal and not to be shared, so do not ask a client for theirs.

The server accepts either kind of token in the same variable, since both are sent as a bearer credential.

Usage

Claude Code

claude mcp add bexio --env BEXIO_API_TOKEN=your-token -- npx -y @aiwerk/mcp-server-bexio

Claude Desktop

{
  "mcpServers": {
    "bexio": {
      "command": "npx",
      "args": ["-y", "@aiwerk/mcp-server-bexio"],
      "env": { "BEXIO_API_TOKEN": "your-token" }
    }
  }
}

AIWerk hosted service

Install it from the catalogue at aiwerkmcp.com and add your token in the interface. No local setup required.

Safety features

Accounting data is not a good place to find out that a tool did something unexpected, so three guards ship by default.

Dry run

export BEXIO_DRY_RUN=1

Every write is stopped inside the process and returns a description of the request that would have been sent. Reads still work normally. Useful for letting an agent plan a change before you allow it to happen.

Pre write snapshots

Before modifying or deleting an existing record, the server fetches its current state and writes it to ~/.aiwerk/bexio-snapshots/. The tool result carries the file path in _snapshot, so the previous state is always recoverable.

Several bexio edit endpoints replace the whole record, which means an omitted field becomes empty. The snapshot is what makes that reversible.

If the snapshot cannot be taken, the write is refused. Set BEXIO_SNAPSHOT_FAIL_OPEN=1 to downgrade that to a warning, or BEXIO_NO_SNAPSHOT=1 to switch snapshots off entirely.

Rate limit handling

bexio applies a per minute limit per company, and the limit is not the same for every endpoint. Measured against a live account, the items endpoint allows 400 requests per minute while contacts, accounts and currencies allow 1000.

The server therefore tracks the remaining allowance separately for each endpoint group, waits out short windows, retries on 429 with the reset hint, and fails with a clear message rather than hanging when the wait would be long.

Configuration

| Variable | Default | Purpose | |---|---|---| | BEXIO_API_TOKEN | required | Personal access token | | BEXIO_API_BASE_URL | https://api.bexio.com | Override the host, applies to all API versions | | BEXIO_API_TIMEOUT_MS | 30000 | Per request timeout | | BEXIO_DRY_RUN | off | 1 blocks all writes | | BEXIO_NO_SNAPSHOT | off | 1 disables pre write snapshots | | BEXIO_SNAPSHOT_FAIL_OPEN | off | 1 allows a write when the snapshot fails | | BEXIO_SNAPSHOT_DIR | ~/.aiwerk/bexio-snapshots | Where snapshots are written | | BEXIO_MAX_RATE_LIMIT_WAIT_MS | 10000 | Longest wait before failing on a rate limit | | BEXIO_ENABLED_TAGS | all | Comma separated domain filter, for example Contacts,Invoices |

Narrowing the tool set

All 310 tools are registered by default. A client that prefers a smaller surface can restrict the server to specific domains:

export BEXIO_ENABLED_TAGS="Contacts,Invoices,Quotes,Items"

Unknown domain names are reported on startup rather than silently ignored.

Tool naming

Tools follow a predictable shape, so an agent that knows one name can guess the rest:

list_contacts      get_contact      create_contact
search_contacts    update_contact   delete_contact

Collection verbs (list_, search_) take a plural noun, single record verbs take a singular one. Document actions keep their own verb: issue_invoice, cancel_invoice, send_invoice, mark_as_sent_invoice, revert_issue_quote.

A few bexio specifics worth knowing

• Three API versions coexist. Contacts, sales documents, items and projects live on 2.0, files and expenses on 3.0, bills and banking on 4.0. The server handles this transparently, but it explains why paths look inconsistent in error messages.
• Document positions require a tax id. The specification does not mark tax_id as required, yet bexio rejects a position without one. Fetch a valid id with list_taxes.
• A 403 does not always mean permissions. bexio also answers 403 when the record's state forbids the operation, for example deleting an invoice that has been issued.
• Contacts have no single address field. Use street_name, house_number, postcode and city.
• contact_type_id is 1 for a company and 2 for a person.

Testing

npm test          # unit tests
npm run smoke     # read only, against a live account

The write paths are covered by a separate script that creates and deletes real records, so it refuses to run without an explicit confirmation:

BEXIO_WRITE_SMOKE=yes node scripts/write-smoke.mjs

Point it at a throwaway trial account, never at production data. It exercises the full lifecycle of contacts, items, invoices and quotes, then cleans up after itself.

Development

The tool layer is generated and must not be edited by hand:

npm run gen-naming   # specification  ->  tool names
npm run gen-tools    # specification  ->  zod schemas and call sites
npm run build

Licence

MIT, see LICENSE.

Built by AIWerk. Not affiliated with bexio AG.