bokio-mcp

一个用于 Bokio 会计 API 的 MCP 服务器。它通过一个 Bokio 公司暴露 85 个工具 —— 发票、客户、供应商、供应商发票、日记账分录、贷项通知单、会计科目表、会计年度、项目、标签、上传、SIE 导出和银行付款 —— 因此 MCP 客户端可以读取并（可选地）写入你的簿记。

无需账户、无需数据库、无需托管服务。每个服务器实例对应一家公司。

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

快速开始

使用固定测试数据试用，无需 Bokio 账户：

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

BOKIO_MOCK=true 会在进程内提供一个模拟的 Bokio，因此在你拥有任何凭据之前，完整的工具面即可工作。

对于真实数据，请从下面两条凭据路线中选择一条，并将服务器添加到你的 MCP 客户端。

路线 A — 私有集成令牌（推荐）

在 Bokio 中：公司设置 → 集成 → API 令牌 → 创建私有集成。该令牌长期有效，范围限定于该公司，且无需 OAuth 审核。

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

路线 B — OAuth

在 Bokio 开发者门户中注册一个集成，重定向 URI 为 http://127.0.0.1:7337/callback，然后：

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

这会在你的浏览器中打开 Bokio，并将令牌写入 ~/.config/bokio-mcp/tokens.json（模式 0600）。访问令牌会自动刷新，包括刷新令牌轮换。将你的 MCP 客户端指向 npx -y bokio-mcp，并设置相同的两个环境变量。

Related MCP server: QuickBooks Online MCP Server

默认关闭写入

全新安装可以读取但不能写入。变更工具不仅仅是被阻止——它们不出现在 tools/list 中，因此模型永远不会提出它无法执行的编辑：

BOKIO_ALLOW_WRITES=true

在 85 个工具中，38 个是只读的，47 个会变更。先不带该标志启动，确认模型读取的内容符合预期，然后再开启写入。

命令

HTTP 传输

用于自托管，例如在反向代理或容器后面：

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

/mcp 随后由该静态 Bearer 令牌保护。如果没有 MCP_AUTH_TOKEN，服务器仅绑定 127.0.0.1，而不是暴露一个未经身份验证的桥梁来访问实时会计数据。附带了一个 Dockerfile；它默认使用此传输方式。

环境变量

参见 .env.example 获取带注释的版本。

关于令牌存储的说明

OAuth 令牌文件以 0600 模式明文存储，除非设置了 BOKIO_TOKEN_ENCRYPTION_KEY —— 这与 gh 和 aws CLI 的做法相同。在个人机器上，将密钥存储在被加密对象旁边作用不大；当文件存放在不太私密的地方（例如容器镜像或共享主机）时，请设置该密钥。

开发

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

BOKIO_MOCK=true 会在 fetch 层将每个 Bokio 请求路由到进程内模拟，因此它在 stdio、HTTP 以及没有服务器运行的测试中表现一致。test/mcp.test.ts 针对它端到端驱动真实的 MCP 协议。

工具定义是手写在 src/tools/bokio/ 中的，但每个工具的路径和方法都会在编译时由 op() 辅助函数对照 OpenAPI 规范进行检查——路由中的拼写错误会导致构建失败。使用以下命令重新生成规范类型：

npm run gen:bokio

不支持

• 每个实例支持多家公司。 Bokio 凭据是按公司划分的；如需第二家公司，请运行第二个实例。

• 提升的范围。 bank-payments:* 需要 Bokio 对每个集成进行单独批准。银行付款工具已注册，但在你的集成获得批准并将范围添加到 BOKIO_SCOPES 之前，它们将无法使用。

许可证

MIT