bokio-mcp

An MCP server for the Bokio accounting API. It exposes 85 tools over one Bokio company — invoices, customers, suppliers, supplier invoices, journal entries, credit notes, the chart of accounts, fiscal years, items, tags, uploads, SIE export and bank payments — so an MCP client can read and (optionally) write your bookkeeping.

No accounts, no database, no hosted service. One company per server instance.

"Which invoices are still unpaid?"
"Book the attached receipt against account 6570."
"Export the SIE file for the 2025 fiscal year."

Quick start

Try it with fixtures, no Bokio account needed:

BOKIO_MOCK=true npx bokio-mcp status
# { "companyName": "Testbolaget AB", "status": "active", ... }

BOKIO_MOCK=true serves an in-process fake Bokio, so the full tool surface works before you have any credentials.

For real data, pick one of the two credential routes below and add the server to your MCP client.

Route A — private integration token (recommended)

In Bokio: company settings → Integrations → API tokens → Create private integration. The token is long-lived, scoped to that one company, and needs no OAuth review.

{
  "mcpServers": {
    "bokio": {
      "command": "npx",
      "args": ["-y", "bokio-mcp"],
      "env": {
        "BOKIO_INTEGRATION_TOKEN": "your-token",
        "BOKIO_COMPANY_ID": "the-company-uuid-from-the-bokio-url"
      }
    }
  }
}

Route B — OAuth

Register an integration in Bokio's developer portal with the redirect URI http://127.0.0.1:7337/callback, then:

export BOKIO_CLIENT_ID=... BOKIO_CLIENT_SECRET=...
npx bokio-mcp login

That opens Bokio in your browser and writes the tokens to ~/.config/bokio-mcp/tokens.json (mode 0600). Access tokens are refreshed automatically, including refresh-token rotation. Point your MCP client at npx -y bokio-mcp with the same two env vars set.

Related MCP server: QuickBooks Online MCP Server

Writes are off by default

A fresh install can read but not write. Mutating tools are not merely blocked — they are absent from tools/list, so the model never proposes an edit it cannot make:

BOKIO_ALLOW_WRITES=true

Of the 85 tools, 38 are read-only and 47 mutate. Start without the flag, confirm the model is reading what you expect, then turn writes on.

Commands

HTTP transport

For self-hosting, e.g. behind a reverse proxy or in a container:

MCP_AUTH_TOKEN=$(openssl rand -hex 32) bokio-mcp serve --http

/mcp is then guarded by that static bearer. Without MCP_AUTH_TOKEN the server binds 127.0.0.1 only rather than exposing an unauthenticated bridge to live accounting data. A Dockerfile is included; it defaults to this transport.

Environment

See .env.example for the annotated version.

A note on token storage

The OAuth token file is plaintext at mode 0600 unless BOKIO_TOKEN_ENCRYPTION_KEY is set — the same posture as the gh and aws CLIs. On a personal machine a key stored next to the thing it encrypts adds little; set it when the file lives somewhere less private, such as a container image or a shared host.

Development

npm install
npm test          # 36 tests, no database, no credentials
npm run typecheck
npm run dev       # tsx watch, stdio transport

BOKIO_MOCK=true routes every Bokio request into an in-process mock at the fetch layer, so it behaves identically under stdio, under HTTP, and inside tests with no server running. test/mcp.test.ts drives the real MCP protocol end to end against it.

Tool definitions are hand-written in src/tools/bokio/, but each one's path and method are checked against the OpenAPI spec at compile time by the op() helper — a typo in a route fails the build. Regenerate the spec types with:

npm run gen:bokio

Not supported

• More than one company per instance. Bokio credentials are per-company; run a second instance for a second company.

• Elevated scopes. bank-payments:* requires per-integration approval from Bokio. The bank payment tools are registered but will fail until your integration is approved and the scopes are added to BOKIO_SCOPES.

License

MIT