Skip to main content
Glama
bokio-mcp

bokio-mcp

by straycatse

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.

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: e-conomic 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

bokio-mcp

Serve over stdio — what MCP clients launch

bokio-mcp serve --http

Serve over streamable HTTP on $PORT

bokio-mcp login

Connect a company via OAuth

bokio-mcp status

Print the current connection and exit

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

Variable

Default

BOKIO_INTEGRATION_TOKEN

—

Route A: private integration token

BOKIO_COMPANY_ID

—

Route A: the company's UUID

BOKIO_CLIENT_ID / BOKIO_CLIENT_SECRET

—

Route B: OAuth credentials

BOKIO_ALLOW_WRITES

false

Register mutating tools

BOKIO_MOCK

false

Serve in-process fixtures instead of Bokio

BOKIO_SCOPES

see src/config.ts

OAuth scopes requested by login

BOKIO_TOKEN_FILE

~/.config/bokio-mcp/tokens.json

Where OAuth tokens live

BOKIO_TOKEN_ENCRYPTION_KEY

—

Optional AES-256-GCM at rest; openssl rand -base64 32

BINARY_MAX_BYTES

4194304

Cap on inline uploads/downloads

PORT / HOST

3000 / auto

HTTP transport

MCP_AUTH_TOKEN

—

Bearer guarding /mcp

OAUTH_CALLBACK_PORT

7337

Loopback port used by login

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

Available Tools

40 tools
bokio_download_credit_noteDownload credit note PDFA
Read-onlyIdempotent

Downloads the credit note as a PDF file.

Inputs: creditNoteId (required).

bokio_download_invoiceDownload invoice PDFA
Read-onlyIdempotent

Downloads the invoice as a PDF file.

Inputs: invoiceId (required).

bokio_download_invoice_attachmentDownload invoice attachmentA
Read-onlyIdempotent

Downloads an invoice attachment file.

Inputs: invoiceId (required), attachmentId (required).

bokio_download_sieDownload SIE fileA
Read-onlyIdempotent

Downloads the SIE export (Swedish standard accounting interchange format) for a fiscal year.

Inputs: fiscalYearId (required).

bokio_download_uploadDownload uploadB
Read-onlyIdempotent

Downloads an uploaded file.

Inputs: uploadId (required).

bokio_get_accountGet accountA
Read-onlyIdempotent

Fetches one account by its number (e.g. 1930).

Inputs: account (required).

bokio_get_bank_paymentGet bank paymentA
Read-onlyIdempotent

Fetches one bank payment created by this integration.

Inputs: bankPaymentId (required).

bokio_get_company_informationGet company informationA
Read-onlyIdempotent

Fetches the company's registered information (name, org number, type, address).

Inputs: no named parameters.

bokio_get_credit_noteGet credit noteC
Read-onlyIdempotent

Fetches one credit note.

Inputs: creditNoteId (required).

bokio_get_customerGet customerB
Read-onlyIdempotent

Fetches one customer.

Inputs: customerId (required).

bokio_get_fiscal_yearGet fiscal yearC
Read-onlyIdempotent

Fetches one fiscal year.

Inputs: fiscalYearId (required).

bokio_get_invoiceGet invoiceA
Read-onlyIdempotent

Fetches one invoice including line items, payments and status.

Inputs: invoiceId (required).

bokio_get_invoice_attachmentGet invoice attachmentB
Read-onlyIdempotent

Fetches attachment metadata.

Inputs: invoiceId (required), attachmentId (required).

bokio_get_invoice_paymentGet invoice paymentA
Read-onlyIdempotent

Fetches one payment on an invoice.

Inputs: invoiceId (required), paymentId (required).

bokio_get_invoice_settlementGet invoice settlementB
Read-onlyIdempotent

Fetches one settlement on an invoice.

Inputs: invoiceId (required), settlementId (required).

bokio_get_itemGet itemB
Read-onlyIdempotent

Fetches one item.

Inputs: itemId (required).

bokio_get_journal_entryGet journal entryB
Read-onlyIdempotent

Fetches one journal entry with its debit/credit items.

Inputs: journalEntryId (required).

bokio_get_journal_entry_commentGet journal entry commentA
Read-onlyIdempotent

Fetches one comment on a journal entry.

Inputs: commentId (required), journalEntryId (required).

bokio_get_supplierGet supplierA
Read-onlyIdempotent

Fetches one supplier.

Inputs: supplierId (required).

bokio_get_supplier_invoiceGet supplier invoiceB
Read-onlyIdempotent

Fetches one supplier invoice.

Inputs: supplierInvoiceId (required).

bokio_get_tag_groupGet tag groupB
Read-onlyIdempotent

Fetches one tag group.

Inputs: tagGroupId (required).

bokio_get_uploadGet uploadA
Read-onlyIdempotent

Fetches metadata for one uploaded file.

Inputs: uploadId (required).

bokio_list_accountsList chart of accountsA
Read-onlyIdempotent

Lists the chart of accounts (kontoplan), optionally filtered by free text.

Inputs: query.

bokio_list_bank_paymentsList bank paymentsB
Read-onlyIdempotent

Lists bank payments created by this integration (limited read).

Inputs: page, query, pageSize.

bokio_list_credit_notesList credit notesA
Read-onlyIdempotent

Lists credit notes with paging and free-text filtering.

Inputs: page, query, pageSize.

bokio_list_customersList customersA
Read-onlyIdempotent

Lists customers with paging and free-text filtering.

Inputs: page, query, pageSize.

bokio_list_fiscal_yearsList fiscal yearsA
Read-onlyIdempotent

Lists the company's fiscal years.

Inputs: page, query, pageSize.

bokio_list_invoice_attachmentsList invoice attachmentsB
Read-onlyIdempotent

Lists file attachments on an invoice.

Inputs: invoiceId (required), page, query, pageSize.

bokio_list_invoice_paymentsList invoice paymentsA
Read-onlyIdempotent

Lists payments registered on an invoice.

Inputs: invoiceId (required), page, query, pageSize.

bokio_list_invoicesList invoicesA
Read-onlyIdempotent

Lists customer invoices with paging and free-text filtering.

Inputs: page, query, pageSize.

bokio_list_invoice_settlementsList invoice settlementsB
Read-onlyIdempotent

Lists settlements on an invoice.

Inputs: invoiceId (required), page, query, pageSize.

bokio_list_itemsList itemsA
Read-onlyIdempotent

Lists inventory/product items with paging and free-text filtering.

Inputs: page, query, pageSize.

bokio_list_journal_entriesList journal entriesA
Read-onlyIdempotent

Lists journal entries (verifikationer) with paging, free-text filter and optional tagId.

Inputs: page, query, tagId, pageSize.

bokio_list_journal_entry_commentsList journal entry commentsB
Read-onlyIdempotent

Lists comments on a journal entry.

Inputs: journalEntryId (required).

bokio_list_supplier_invoicesList supplier invoicesA
Read-onlyIdempotent

Lists supplier invoices with paging and free-text filtering.

Inputs: page, query, pageSize.

bokio_list_suppliersList suppliersA
Read-onlyIdempotent

Lists suppliers with paging and free-text filtering.

Inputs: page, query, pageSize.

bokio_list_tag_groupsList tag groupsB
Read-onlyIdempotent

Lists tag groups (cost centers, projects, etc.) with their tags.

Inputs: page, query, pageSize.

bokio_list_uploadsList uploadsB
Read-onlyIdempotent

Lists uploaded files (receipts, documents) with paging.

Inputs: page, query, pageSize.

get_connection_statusGet connection statusA
Read-onlyIdempotent

Shows which Bokio company this server is connected to, the health of its access token, and whether write operations are enabled. Call this first if another tool reports an authentication problem.

Inputs: no named parameters.

pingA
Read-only

Health check: verifies the MCP connection is working.

Inputs: no named parameters.

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    TDQS

    A3.6/5.0

    Scored across 40 tools

    Disambiguation5/5

    Each tool targets a distinct entity or action (list vs get vs download) with clear hierarchical relationships (e.g., invoice → payments/settlements/attachments). No overlapping purposes that would cause misselection.

    Naming Consistency5/5

    All domain tools follow a strict 'bokio_verb_noun' pattern (list/get/download), with utility tools (ping, get_connection_status) clearly separated. The naming is highly predictable and consistent.

    Tool Count4/5

    With 40 tools, the count is on the heavier side but justified by the breadth of accounting entities (invoices, customers, journal entries, items, uploads, etc.). Each tool serves a specific resource, though some consolidation could reduce redundancy.

    Completeness3/5

    The tool surface comprehensively covers read operations across all major accounting entities, including downloads and SIE export. However, it lacks any create/update/delete tools, so the lifecycle is incomplete unless the server is intentionally read-only.

    Maintenance

    ActivityInactive
    ResponsivenessNo recent community issues

    Related MCP Connectors

    Related MCP Servers

    • A
      license
      A
      quality
      B
      maintenance
      Enables interaction with the Bokio accounting API for managing journal entries, invoices, customers, items, and more, with read-only mode by default for safety.
      37
      85 npm
      3
      MIT
    • F
      license
      Not graded
      quality
      B
      maintenance
      Exposes Visma e-conomic REST API as 73 MCP tools for managing customers, suppliers, products, invoices, quotes, orders, accounting, and reference data, with secure authentication, allowlist, read-only mode, and audit logging.
      -
    • A
      license
      Not graded
      quality
      C
      maintenance
      Enables MCP-capable clients to read and write directly in epago accounting, including chart of accounts, transactions, invoices, payments, receipts, and tax reports.
      MIT
    • A
      license
      B
      quality
      C
      maintenance
      Enables MCP clients to read invoices, supplier invoices, vouchers, financial reports, and AR/AP ageing from a Swedish accounting system, with optional draft-only write tools for customers, offers, orders, and unsent invoice drafts after confirmation. It also exposes many other read endpoints through a safety allowlist.
      26
      1
      MIT