mcp-buchhaltungsbutler

Deutsch | English

BuchhaltungsButler（ドイツの簿記・会計SaaS）のAPI（v1）を、LLMエージェント向けに厳選したトークン効率の良いツール群として公開するMCP（Model Context Protocol）サーバーです。

非公式のコミュニティプロジェクトです。BuchhaltungsButlerとは提携しておらず、承認も受けていません。

エージェント向けに構築、単なるAPIラッパーではありません

• 全48エンドポイントをカバーする30ツール — 同じアクションの一括・一覧・単一のバリエーションは1つのツールに統合されるため、コンテキストウィンドウがほぼ重複したツール定義で埋まることはありません。

• デフォルトで最小限 — 一覧ツールは、通常はLLMに適したトリミング済みフィールドを返します。完全なレコードが必要な場合は full: true を渡してください。

• 配列の扱いに煩わされない — 請求書の明細行、転記の分割、その他のAPIの癖は、すっきりとした通常のオブジェクトとして公開されます。5つの並列配列を手動で同期する必要はもうありません。

• 常に仕様と同期 — エンドポイント定義はBuchhaltungsButlerの公式API仕様から直接生成されており、手動で管理されていません。

Related MCP server: Cuéntica MCP

セットアップ

1. npm install

2. .env.example を .env にコピーし、BB_API_CLIENT、BB_API_SECRET、BB_API_KEY（BuchhaltungsButler → 設定 → API）を記入します。

3. npm test — モック化されたHTTPレスポンスに対して実行されるため、実際の資格情報は不要です。

4. npm run build && npm start — または、ビルドせずに手早くローカルで実行するには npm run dev を使用します。

npm run generate は、ベンダー提供の仕様（spec/buchhaltungsbutler-v1.json）から src/bb-client/generated/endpoints.ts を再生成します。出力はすでにコミットされているため、この操作は仕様ファイル自体を更新した後にのみ必要です。

MCPクライアントでの使用

.env はローカルの npm run dev / npm start 実行のみを対象としています。実際のMCPクライアント（例：Claude Desktop）はサーバー自体を起動するため、.env を読み取りません。クライアント自身の env 設定を介して資格情報を渡してください。claude_desktop_config.json のエントリ例：

{
  "mcpServers": {
    "buchhaltungsbutler": {
      "command": "node",
      "args": ["/absolute/path/to/mcp-buchhaltungsbutler/dist/index.js"],
      "env": {
        "BB_API_CLIENT": "your-api-client",
        "BB_API_SECRET": "your-api-secret",
        "BB_API_KEY": "your-customer-api-key"
      }
    }
  }
}

先に npm run build を実行して dist/index.js が存在することを確認してください。

ツール

アーキテクチャ

src/
  config.ts              # env var loading, fail-fast validation
  bb-client/
    generated/            # spec-derived endpoint metadata (regenerate with npm run generate)
    client.ts              # generic HTTP client: auth, api_key injection, error mapping
  formatting/trim.ts       # trims list responses to LLM-friendly fields
  tools/                   # one file per category, curated MCP tools on top of the client
  server.ts, index.ts      # MCP server bootstrap (stdio)
scripts/generate-client.ts # parses spec/buchhaltungsbutler-v1.json into src/bb-client/generated/

シングルテナント、ローカルのstdioトランスポートのみ。リモートホスティング、マルチテナントサポート、OAuthはありません。資格情報がモデルに到達することはなく、env変数からクライアントレイヤーによってリクエストに挿入されます。

状態

上記の30ツールでBuchhaltungsButlerの全48エンドポイントをカバーし、モック化されたHTTPレスポンスでテストされています。実際のアカウントでの検証はまだ行われていません。特に、4つの *_id_by_customer で終わるエンドポイント（get_receipt、set_receipt_deleted、get_transaction）や、コスト場所が混在する add_receipt_postings / add_transaction_postings で予期しないエラーが発生した場合は、issueを開いてください。

開発

git clone https://github.com/si0nDE/mcp-buchhaltungsbutler.git && cd mcp-buchhaltungsbutler
npm install
npm test           # vitest run
npm run build       # tsc, strict mode