bokio-mcp

Bokio 会計API向けの MCP サーバーです。1つのBokio会社に対して 85のツール を公開します — 請求書、顧客、仕入先、仕入先請求書、仕訳、クレジットノート、勘定科目表、会計年度、品目、タグ、アップロード、SIEエクスポート、銀行支払いなど — MCPクライアントはこれらを通じて帳簿を読み取り、(オプションで)書き込むことができます。

アカウントもデータベースもホスト型サービスも不要です。サーバーインスタンス1つにつき会社1社です。

"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を提供するため、認証情報がなくても全ツールが動作します。

実際のデータを使う場合は、以下の2つの認証ルートのいずれかを選び、MCPクライアントにサーバーを追加してください。

ルートA — プライベート統合トークン(推奨)

Bokioで: 会社設定 → 統合 → APIトークン → プライベート統合を作成。トークンは長期有効で、その1社にスコープされ、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

リダイレクトURI http://127.0.0.1:7337/callback を指定してBokioの開発者ポータルで統合を登録し、次を実行します:

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

これによりブラウザでBokioが開き、トークンが ~/.config/bokio-mcp/tokens.json(モード 0600)に書き込まれます。アクセストークンはリフレッシュトークンのローテーションを含め、自動的に更新されます。MCPクライアントには、同じ2つの環境変数を設定した上で 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 はその静的ベアラーで保護されます。MCP_AUTH_TOKEN がない場合、サーバーは 127.0.0.1 のみにバインド され、認証なしのブリッジを実在の会計データに公開することはありません。Dockerfile が同梱されており、このトランスポートがデフォルトです。

環境

注釈付きバージョンは .env.example を参照してください。

トークン保存に関する注意

OAuthトークンファイルは、BOKIO_TOKEN_ENCRYPTION_KEY が設定されていない限り、モード 0600 の平文です — 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 はすべてのBokioリクエストを fetch レイヤーでプロセス内モックにルーティングするため、stdioでもHTTPでも、サーバーを起動しないテスト内でも同じように動作します。test/mcp.test.ts は、これに対して実際のMCPプロトコルをエンドツーエンドで駆動します。

ツール定義は src/tools/bokio/ に手書きされていますが、各ツールのパスとメソッドは op() ヘルパーによってコンパイル時にOpenAPI仕様と照合されます — ルートのタイプミスはビルドを失敗させます。仕様タイプを再生成するには:

npm run gen:bokio

サポート外

• インスタンスあたり複数会社。 Bokioの認証情報は会社単位です。2社目には2つ目のインスタンスを実行してください。

• 拡張スコープ。 bank-payments:* はBokioからの統合ごとの承認が必要です。銀行支払いツールは登録されていますが、統合が承認され、スコープが BOKIO_SCOPES に追加されるまで失敗します。

ライセンス

MIT