mcpField
B
BuchhaltungsButler

BuchhaltungsButler

ローカル
github.com金融データ91 日前に更新

BuchhaltungsButler について

BuchhaltungsButlerは、AIアシスタントから自然言語でBuchhaltungsButlerの会計業務を扱えるMCPサーバーです。公式API仕様からセキュリティ分類付きの46個のツールを生成し、stdioとStreamable HTTPに対応します。

主な機能

  1. 01BuchhaltungsButler APIを扱う46個のツール
  2. 02読み取り・書き込み・破壊的操作の分類
  3. 03ツール向けMCP安全性アノテーション
  4. 04stdioとStreamable HTTPのトランスポート
  5. 05レート制限とHTTP Bearer認証
  6. 06サーバー側での認証情報注入

活用シーン

  1. 01指定期間の未処理レシートを一覧表示
  2. 02請求書の下書きや仕入先の作成
  3. 03銀行取引を勘定科目に割り当て
  4. 04レポート作成と勘定明細の取得

MCP 対応

BuchhaltungsButler APIの操作用ツール46個をMCPクライアントに公開します。stdioとStreamable HTTPに対応し、ツール操作に安全性の分類とアノテーションを付けます。

設定

ローカルサーバーの設定はどのクライアントでも共通です。コピーしてクライアントの MCP 設定ファイルに貼り付けてください。

mcp.json · 共通設定
{
"mcpServers": {
"ohneben-buchhaltungsbutler": {
"command": "docker",
"args": [
"run",
"-i",
"--rm",
"-e",
"MCP_TRANSPORT",
"-e",
"BB_API_CLIENT",
"-e",
"BB_API_SECRET",
"-e",
"BB_API_KEY",
"-e",
"BB_RATE_LIMIT",
"-e",
"BB_BASE_URL",
"ghcr.io/ohneben/buchhaltungsbutler-mcp:1.1.4"
],
"env": {
"MCP_TRANSPORT": "<MCP_TRANSPORT>",
"BB_API_CLIENT": "<BB_API_CLIENT>",
"BB_API_SECRET": "<BB_API_SECRET>",
"BB_API_KEY": "<BB_API_KEY>",
"BB_RATE_LIMIT": "<BB_RATE_LIMIT>",
"BB_BASE_URL": "<BB_BASE_URL>"
}
}
}
}
起動コマンドdocker run -i --rm -e MCP_TRANSPORT -e BB_API_CLIENT -e BB_API_SECRET -e BB_API_KEY -e BB_RATE_LIMIT -e BB_BASE_URL ghcr.io/ohneben/buchhaltungsbutler-mcp:1.1.4
設定が必要な環境変数
MCP_TRANSPORTTransport des Servers. Fuer lokale MCP-Clients auf 'stdio' setzen; das Image startet sonst den HTTP-Transport.
BB_API_CLIENTシークレットBuchhaltungsButler API-Client (HTTP-Basic-Benutzername). Zu finden unter Einstellungen -> API.
BB_API_SECRETシークレットBuchhaltungsButler API-Secret (HTTP-Basic-Passwort). Zu finden unter Einstellungen -> API.
BB_API_KEYシークレットapi_key des Mandanten, auf dem gearbeitet wird. Zu finden in den Firmendaten des Kunden.
BB_RATE_LIMITClientseitiges Limit an Anfragen pro Minute. BuchhaltungsButler erlaubt 100 pro Kunde und Minute.
BB_BASE_URLUeberschreibt die API-Basis-URL. Standard ist der Wert aus der mitgelieferten Spec.

ローカルサーバーにはマシン上の実行環境(Node.js 18 以上など)が必要です。設定ファイルの場所はクライアントごとに異なります。

パッケージ
ocighcr.io/ohneben/buchhaltungsbutler-mcp:1.1.4

ツール

ツール一覧はまだ取得されていません

ローカルサーバーのツールはマシン上で起動して初めて取得できます。メンテナーはまだツール一覧を提供していません。

詳細

ohneben の Buchhaltungsbutler MCP

Buy Me A Coffee


ライセンスとチェック

CI ライセンス:MIT

MCP レジストリ

MCP Registry mcpservers.org に掲載 Buchhaltungsbutler-MCP MCP server

パッケージ識別子

このサーバーには固有の識別子があります。名称が異なるものは別のものです。

場所識別子
MCP レジストリio.github.ohneben/buchhaltungsbutler-mcp
コンテナ(GHCR)ghcr.io/ohneben/buchhaltungsbutler-mcp
npm@ohneben/buchhaltungsbutler-mcp(未公開)

スコープのない npm パッケージ buchhaltungsbutler-mcp は、別の作者による別のプロジェクト(mrvnklm/buchhaltungsbutler-mcp)であり、このプロジェクトとは関係ありません。このページからそちらへリンクしているディレクトリは、誤ったパッケージへリンクしています。

Claude、Cursor などの AI アシスタントから、自然言語で BuchhaltungsButler の会計業務を管理できます。

この Model-Context-Protocol サーバーは、 BuchhaltungsButler API v1 を提供します。 公式 OpenAPI 仕様(仕様バージョン 1.9.1)から生成された、54 個のエンドポイントを 46 個の MCP ツールとして利用できます。各ツールは安全性に応じて分類されており (読み取り専用/書き込み/破壊的)、アシスタントは実行する前に各操作の内容を 把握できます。stdio(Claude Desktop などのローカルランチャー)または Streamable HTTP(Docker でホスト)で動作します。

このサーバーを使う理由

一部の MCP サーバーは、API をそのまま中継するだけです。このサーバーは、 安心して言語モデルに渡せること、そして日常的に運用できることを念頭に設計されています。

得られるもの重要な理由
公式仕様から54 個すべてのエンドポイントを自動生成証憑、取引、仕訳、請求書、分析、マスターデータを完全にカバーします。手作業で選別したり、見落としたりすることはありません。
すべてのツールをセキュリティ分類 🟢 / 🟡 / 🔴各ツールの説明の冒頭に表示されるバナーで、モデルは操作する前に、読み取り、新規作成、変更、取り消し、削除のどれが行われるかを正確に把握できます。
機械可読な MCP アノテーション(readOnlyHint、destructiveHint)アノテーションを評価するホスト(Claude など)は、読み取りを自動的に許可し、破壊的な操作の前に確認を求めることができます。
2 種類のトランスポート:stdio および Streamable HTTPClaude Desktop でローカル利用することも、任意の数の MCP クライアントが HTTP 経由でアクセスできる常時稼働サーバーを運用することもできます。
Docker + docker-compose、ヘルスチェック、自動再起動本番環境に近いデプロイをすぐに利用できます。docker compose up を実行すれば、サーバーは稼働し続けます。
HTTP エンドポイントでのBearer トークン認証サーバーをループバック以外にバインドする場合は必須です。MCP_AUTH_TOKEN がない場合、API を無防備な状態で公開するのではなく、起動を拒否します。
組み込みのレート制限BuchhaltungsButler の顧客あたり毎分 100 リクエストという制限を下回るよう、自動的に速度を調整します。これにより、制限に達することがありません。
認証情報がモデルに渡ることはありません認証情報はサーバー環境に保存され、リクエストごとに注入されます。アシスタントに見えるのはツールへの入力と API の応答だけです。
比較

現時点では、BuchhaltungsButler 専用の MCP サーバーはこれだけです。 代わりに、汎用の OpenAPI→MCP ラッパーを仕様に適用することもできますが、 その場合はいくつかの機能が不足します。

機能このプロジェクト汎用 OpenAPI→MCP ラッパー*
BuchhaltungsButler の 54 個すべてのエンドポイントをカバー✅✅
🟢 / 🟡 / 🔴 のセキュリティ分類 + ツールごとのバナー✅❌
readOnlyHint / destructiveHint MCP アノテーション✅➖
$ref の解決(バッチペイロード用)+ HTML を除去した説明✅➖
組み込みのレート制限(BB の顧客あたり毎分 100 件未満に維持)✅❌
stdio トランスポート✅✅
Streamable HTTP トランスポート✅➖
Docker + docker-compose、ヘルスチェック、自動再起動✅❌
エンドポイントでBearer トークン認証を強制✅❌
認証情報をサーバー側で注入し、モデルに送信しない✅➖
ライセンスMITさまざま

*汎用 OpenAPI→MCP ラッパーは、あらゆる Swagger/OpenAPI 仕様を MCP ツールに変換します。 同じエンドポイントにアクセスできますが、すべての操作を同じように扱います。セキュリティ分類も、運用面の考慮も、実際の会計データに合わせたガードレールもありません。「➖」=ツールによって異なる/保証されない。

できること

サーバーを接続すると、たとえば次のようにアシスタントに依頼できます。

  • 「先月分で、まだ未決済の仕入証憑をすべて一覧表示して。」
  • 「ACME GmbH 宛てに、1 時間あたり 120 € で 10 時間分のコンサルティング請求書の下書きを作成して。」
  • 「この銀行取引を総勘定元帳の勘定科目 4400 に記帳して。」
  • 「この PDF の証憑をアップロードして、該当する取引に紐付けて。」
  • 「仕入先を表示して、ホスティングプロバイダーの新しい仕入先を登録して。」
  • 「前四半期の BWA を作成して、勘定科目 4400 の勘定明細も表示して。」

ツールは公式 API から自動生成され、読み取り専用の 🟢、書き込みの 🟡、破壊的操作の 🔴 に分類されます。適切に実装されたホストであれば、各グループを異なる方法で扱うことができます。

仕組み

Claude / Cursor / beliebiger MCP-Client  ──MCP──►  dieser Server  ──HTTPS──►  BuchhaltungsButler API (Cloud)

サーバーは付属のOpenAPI仕様を読み込み、MCPツールに変換します($refを含むバッチペイロードの解決や、説明文からのHTMLの削除も行います)。各ツールにセキュリティカテゴリを設定し、Basic認証の認証情報とapi_keyをすべての送信リクエストに付加します。認証情報はサーバー環境内にとどまり、モデルが見ることも扱うこともありません。

前提条件

  • APIアクセス権のあるBuchhaltungsButlerアカウント — API Client + API Secret(設定 → API)と、顧客の**api_key** (API認証情報の取得を参照)。
  • 以下のクイックスタートにはDocker(macOS/WindowsではDocker Desktop)、またはソースコードから起動するにはNode.js ≥ 18が必要です。

クイックスタート(Docker)

1. 認証情報を設定する。 サンプル設定をコピーして、値を入力します。

cp .env.example .env
# .env bearbeiten → BB_API_CLIENT, BB_API_SECRET, BB_API_KEY setzen
#                 → MCP_AUTH_TOKEN setzen. PFLICHT, sonst startet der Server
#                   nicht, denn .env.example bindet auf 0.0.0.0:
#                   openssl rand -hex 32

2. サーバーを起動する。

docker compose up -d --build

3. 起動していることを確認する。

curl -s http://localhost:3000/health     # → {"status":"ok","server":"buchhaltungsbutler-mcp"}

4. MCPクライアントを接続する。 リモートエンドポイントは、Claudeのカスタムコネクターとして追加するか(設定 → コネクター)、ローカルでmcp-remoteを使って中継します。クライアント設定のmcpServersに以下を入力し、その後アプリを完全に再起動します。

{
  "mcpServers": {
    "buchhaltungsbutler": {
      "command": "npx",
      "args": [
        "mcp-remote",
        "http://localhost:3000/mcp",
        "--header", "Authorization: Bearer DEIN_MCP_AUTH_TOKEN"
      ]
    }
  }
}

(ループバックにトークンなしでバインドする場合に限り、--headerの行を省略できます。 上記のDockerクイックスタートではトークンが必須です。)

完成済みのイメージを使いますか?

mainへのプッシュごとに、GitHub Container Registryで起動準備済みのイメージが公開されます。これを使えばローカルでのビルドを完全に省略できます。

docker run -d --name buchhaltungsbutler-mcp -p 3000:3000 --env-file .env \
  ghcr.io/ohneben/buchhaltungsbutler-mcp:latest

API認証情報の取得

BuchhaltungsButlerでは、2段階の認証を使用します(公式ドキュメントを参照)。

  1. HTTP Basic認証 — グローバルなAPI認証情報であるAPI ClientとAPI Secretです。BuchhaltungsButlerの設定 → APIで確認または作成できます。
  2. api_key — リクエストの対象となる顧客アカウントを指定します。各顧客の会社情報設定に記載されています。

3つの値すべてを.envに入力してください。サーバーが各リクエストに値を付加するため、アシスタントに見られることはありません。1回のツール呼び出しに独自のapi_keyを指定して、別の顧客アカウントにアクセスすることもできます。

設定

すべて .env に設定します(.env.example からコピーします)。

変数必須デフォルト説明
BB_API_CLIENT✅—API クライアント(Basic 認証のユーザー名)
BB_API_SECRET✅—API シークレット(Basic 認証のパスワード)
BB_API_KEY✅—デフォルトの顧客 api_key
MCP_TRANSPORT—stdiostdio または http(Docker イメージではデフォルトで http を使用します)
PORT—3000リッスンする HTTP ポート
HOST—0.0.0.0HTTP バインドアドレス
MCP_HTTP_PATH—/mcpMCP の HTTP ルート
MCP_AUTH_TOKEN⚠️(無効)/mcp で Authorization: Bearer <Token> を要求します。HOST がループバックアドレスでない場合は必須です。設定されていないとサーバーは起動しません
MCP_ALLOWED_HOSTS—(自動)許可する Host ヘッダー(カンマ区切り)。DNS リバインディング対策です。リバースプロキシの背後で必要です
MCP_ALLOW_INSECURE—(無効)トークンなしの場合の起動拒否を解除します。到達不能であることが確実なエンドポイントでのみ使用してください
MCP_SESSION_TTL—1800セッションが破棄されるまでのアイドル時間(秒)
MCP_MAX_SESSIONS—256同時セッション数の上限
BB_ALLOW_API_KEY_OVERRIDE—(無効)ツール呼び出しによる api_key の上書きを許可します
BB_RATE_LIMIT—90クライアント側の1分あたりのリクエスト制限
BB_READ_TIMEOUT_MS—55000すべての試行を通じた読み取りツールの総時間予算(ミリ秒)。SDK クライアントがタイムアウトする60秒より短い値です
BB_READ_RETRIES—2時間予算が残っている場合に、タイムアウト、ネットワークエラー、HTTP 429/502/503/504 の後で読み取りツールを再試行する回数(最大5回)。クライアントが中断した場合、再試行は開始されません。書き込みツールは再試行されず、タイムアウトもありません
BB_BASE_URL—(仕様から取得)API のベース URL を上書きします

.env の変更後は、docker compose up -d --force-recreate で再読み込みします。

ツール名

各ツールの名前は <リソース>_<動詞> です。動詞は list、get、 create、update、delete、upload、assign、unassign、unconfirm、 restore、cancel に固定されています。これにより、BB のパスの表記に かかわらず、同じものはどこでも同じ名前になります(API では add と create が混在し、2つのバッチパスは camelCase です)。

作成は常に、リストを受け取るツールを使います。receipts_create は 領収書を1件でも100件でも作成し、単一のレコードは1件の要素を持つリストです。 そのため、54個のエンドポイントに対してツールは46個です。単独の エンドポイント8個は、それぞれに対応するバッチ版に統合されています。

旧名も引き続き呼び出せます

1.1.1 までの名前も引き続き機能します。カタログには表示されませんが、 旧リリースの固定された呼び出しが機能しなくならないよう、呼び出し時に 解決されます。単一フィールドを指定して receipts_add を呼び出すと、 引き続き /receipts/add に送られます。

BB_READ_ONLY と BB_TOOL_ALLOWLIST は先に適用されます。旧名を使っても、 ポリシーで除外されたツールにはアクセスできません。

旧名(1.1.1 まで)新名
accounts_getaccounts_list
receipts_getreceipts_list
receipts_get_id_by_customerreceipts_get_by_id
receipts_add, receipts_addBatchreceipts_create
transactions_add, transactions_addBatchtransactions_create
settings_get_creditorscreditors_list
settings_add_creditor, settings_add_batch_creditorscreditors_create
settings_get_postingaccountspostingaccounts_list
postings_add_free, postings_add_batch_freepostings_create_free
transactions_assign_receipt, transactions_assign_batch_receipttransactions_assign_receipts

完全な対応表は src/naming.ts にあります。

ツールのセキュリティカテゴリ

各ツールの説明は、次のバナーのいずれかで始まり、適切な MCP アノテーションが付与されています。

バナー数readOnlyHintdestructiveHint意味
🟢 読み取り専用15truefalseデータを取得するだけです。安全です。
🟡 書き込み · データを作成17falsefalseレコードを作成します(冪等ではないため、複数回呼び出すと重複が生じます)。
🟡 書き込み · データを変更4falsefalse既存の基本データを直接変更します。
🟡 書き込み · 紐付け/解除3falsefalse伝票と取引を紐付けるか、紐付けを解除します。元に戻せます。
🟡 書き込み · 状態を戻す4falsefalse仕訳を未確定にするか、伝票を復元します。元に戻せます。
🔴 破壊的 · 削除3falsetrueレコードを削除または取り消します。事前に確認してください。

アノテーションを尊重するホスト(Claude など)では、destructiveHint のツールに確認を求めたり、readOnlyHint のツールを自動的に信頼したりできます。

各ツールには、成功時の応答の形式を示す outputSchema も用意されています。そのため、呼び出しが成功すると、応答はテキストだけでなく structuredContent としても返されます。

npm run list-tools を実行すると(認証情報なしで)、いつでもカタログ全体を出力できます。

🟢 読み取り専用(15)
ツールエンドポイント
accounts_listPOST /accounts/get
cost_locations_listPOST /cost-locations/get
creditors_listPOST /settings/get/creditors
debtors_listPOST /settings/get/debtors
postingaccounts_listPOST /settings/get/postingaccounts
postings_listPOST /postings/get
receipts_get_by_idPOST /receipts/get/id_by_customer
receipts_listPOST /receipts/get
receipts_list_assigned_transactionsPOST /receipts/assigned-transactions/get
reports_get_bwaPOST /reports/get/bwa
reports_get_sumsPOST /reports/get/sums
reports_get_sums_ledgerPOST /reports/get/sums/ledger
transactions_get_by_idPOST /transactions/get/id_by_customer
transactions_listPOST /transactions/get
transactions_list_assigned_receiptsPOST /transactions/assigned-receipts/get
🟡 書き込み · データを作成(17)

2 つのエンドポイントがあるツールは、リストを受け取ります。代わりに単一のフィールドで呼び出すと、単一レコード用のエンドポイントに送られます。

ツールエンドポイント単一レコード用エンドポイント
accounts_createPOST /accounts/add
comments_createPOST /comments/add
cost_locations_createPOST /cost-locations/add
creditors_createPOST /settings/add-batch/creditorsPOST /settings/add/creditor
debtors_createPOST /settings/add-batch/debtorsPOST /settings/add/debtor
invoices_createPOST /invoices/create
invoices_create_draftPOST /invoices/create/draft
invoices_create_e_invoicePOST /invoices/create/e-invoice
postingaccounts_createPOST /settings/add/postingaccount
postings_create_for_receiptPOST /postings/add-batch/receiptsPOST /postings/add/receipt
postings_create_for_transactionPOST /postings/add-batch/transactionsPOST /postings/add/transaction
postings_create_freePOST /postings/add-batch/freePOST /postings/add/free
receipts_createPOST /receipts/addBatchPOST /receipts/add
receipts_uploadPOST /receipts/upload
reports_create_bwaPOST /reports/create/bwa
reports_create_sumsPOST /reports/create/sums
transactions_createPOST /transactions/addBatchPOST /transactions/add
🟡 書き込み · 変更(4)· 関連付け(3)· 取り消し(4)
ツールエンドポイントサブカテゴリ
cost_locations_updatePOST /cost-locations/update変更
creditors_updatePOST /settings/update/creditor変更
debtors_updatePOST /settings/update/debtor変更
postingaccounts_updatePOST /settings/update/postingaccount変更
postings_assign_receipt_to_freePOST /postings/assign/receipt-to-free-posting関連付け
transactions_assign_receiptsPOST /transactions/assign-batch/receipt関連付け
transactions_unassign_receiptPOST /transactions/unassign/receipt関連付け
postings_unconfirm_freePOST /postings/unconfirm/free取り消し
postings_unconfirm_for_receiptPOST /postings/unconfirm/receipt取り消し
postings_unconfirm_for_transactionPOST /postings/unconfirm/transaction取り消し
receipts_restorePOST /receipts/restore/id_by_customer取り消し
🔴 破壊的 · 削除(3)
ツールエンドポイント備考
receipts_deletePOST /receipts/delete/id_by_customerreceipts_restore で復元できます
cost_locations_deletePOST /cost-locations/delete復元できません
postings_cancelPOST /postings/cancelまだ確定していない仕訳は削除され、確定済みの仕訳は取消仕訳で相殺されます
v1 APIでできないこと

以下の不足点は、存在しないエンドポイントをモデルが探さないよう、ツールの説明にも意図的に記載しています。

リソース不足している機能
買掛先、売掛先、勘定科目削除できません
勘定科目(accounts)変更も削除もできません
コメント読み取り、変更、削除ができません
請求書読み取り、変更、取消ができません
取引変更も削除もできません

ソースコードから起動する(stdio、Docker 不要)

Claude Desktop で従来の stdio モードを使いますか? その場合は、ローカルでビルドします。

npm install
npm run build

次に、Claude Desktop の claude_desktop_config.json で、コンパイル済みのエントリーポイントを指定します。

{
  "mcpServers": {
    "buchhaltungsbutler": {
      "command": "node",
      "args": ["/ABSOLUTER/PFAD/Buchhaltungsbutler MCP/dist/index.js"],
      "env": {
        "MCP_TRANSPORT": "stdio",
        "BB_API_CLIENT": "dein-api-client",
        "BB_API_SECRET": "dein-api-secret",
        "BB_API_KEY": "dein-kunden-api-key"
      }
    }
  }
}

または、コンテナを stdio 経由で実行します。

{
  "mcpServers": {
    "buchhaltungsbutler": {
      "command": "docker",
      "args": [
        "run", "-i", "--rm",
        "-e", "MCP_TRANSPORT=stdio",
        "-e", "BB_API_CLIENT", "-e", "BB_API_SECRET", "-e", "BB_API_KEY",
        "buchhaltungsbutler-mcp:latest"
      ],
      "env": {
        "BB_API_CLIENT": "dein-api-client",
        "BB_API_SECRET": "dein-api-secret",
        "BB_API_KEY": "dein-kunden-api-key"
      }
    }
  }
}

(先にイメージをビルドしてください:docker build -t buchhaltungsbutler-mcp:latest .)

Specを最新の状態に保つ

同梱の spec.json は、ツールの正式な情報源である BuchhaltungsButler v1 の公式 OpenAPI Spec です。これを新しい API の状態に更新する方法は次のとおりです。

curl -s https://app.buchhaltungsbutler.de/docs/api/v1.de.json -o spec.json
npm run build

新しいパスは自動的に取り込まれます。適切なセキュリティカテゴリを割り当てるため、src/categories.ts の PATH_CATEGORY に追加してください(割り当てのないパスは、安全側に倒して create カテゴリになります)。

バージョン番号について: BuchhaltungsButler では Spec の info.version フィールドが一貫して更新されていません。番号が上がらなくても、内容が変更される場合があります。 そのため、照合時はバージョンに頼らず、パス一覧(paths)とエンドポイントのパラメーターを比較してください。

開発

修正済みの仕訳・関連付けレスポンス、部分的なエラー、書き込み結果が不明な場合については、領収書の仕訳と支払いの関連付けを参照してください。

npm install
npm run build      # TypeScript → dist/ kompilieren
npm test           # Vitest-Suite ausführen
npm run list-tools # kategorisierten Tool-Katalog ausgeben (ohne Zugangsdaten)

CI は Node 20 および 22 で各プッシュのビルドとテストを実行します。main へのプッシュでは、GitHub Container Registry に Docker イメージも公開されます。

独自の API アクセス情報を使った補足的な確認については、読み取り専用の API/MCP 検証を参照してください。通常のテストスイートでは合成データを使用するため、アクセス情報は不要です。

注意事項と規約

  • 日付:YYYY-MM-DD。金額:小数点にはピリオドを使用します(例:-12.30)。
  • ファイルのアップロード(receipts_upload):ファイルはBase64文字列として fileフィールドに渡します。receipts_createはファイルなしで領収書を作成します。
  • ページ分割:ほとんどのlistツールはlimitとoffsetを受け付けます。検証済みの 領収書、取引、仕訳のリストでは、rowsは現在のページのみを数え、全件数は示しません。 重複IDや進捗がない場合は検出してください。最終ページが空であることや重複排除だけでは、 完全性を証明できません。実地テストでは、フィルターを適用した取引ページに重複がある一方、 欠落しているIDもありました。transactions_listでは、フィルターを固定し、offsetを 使わずにid_by_customer_fromとlimitを利用する方法を推奨します。カーソルは排他的で、 IDの昇順ソートを強制します。0から始め、次のカーソルには取得した最大のIDをそのまま設定 してください。IDと進捗を確認し、空のページになるまで続けたうえで、別途照合してください。 詳細と制限事項:読み取り専用の検証。
  • 単一レコードの取得:receipts_get_by_idとtransactions_get_by_idには、それぞれの リストツールから取得した正の整数id_by_customerが必要です。サーバーはこの番号をAPIパスに 挿入します。
  • 作成は常に、配列を受け取るツールを介して行います。アイテムのスキーマはSpecの定義から 解決され、モデルに渡されます。単一レコードの場合は、エントリが1つの配列を使用します。
  • レポート(BWA、試算表)はバックグラウンドで非同期に生成されます。まず reports_create_*を呼び出し、続いて返されたid_by_customerを指定してreports_get_*を 呼び出します。同じ種類の新しいレポートを作成すると、前のレポートが置き換えられます。
  • 勘定元帳:reports_get_sums_ledgerに必要なのは、仕訳勘定番号と期間だけです。APIから直接 取得でき、事前に生成したSuSaやレポートIDは必要ありません。
  • レート制限:BuchhaltungsButlerでは、顧客ごとに1分あたり100件のリクエストが許可されています。 この上限を確実に下回るよう、サーバーはBB_RATE_LIMIT(デフォルトは90)で自らを調整します。

セキュリティ

  • API 認証情報は .env のみに保存され、このファイルは Git の対象外です。**実際の秘密情報をコミットしないでください。**万一漏えいした場合は、BuchhaltungsButler → Einstellungen → API で認証情報をローテーションしてください。
  • HTTP エンドポイントをループバック以外にバインドする場合は、トークンが必須です。 MCP_AUTH_TOKEN が設定されていない場合、サーバーは起動を拒否し、エラーメッセージで必要な対応を説明します。トークンは Authorization: Bearer <Token> ヘッダーで送信してください。可能であれば TLS の背後で使用してください。
  • **localhost でも同様です。**トークンがない場合、任意の Web サイトが DNS リバインディングによってエンドポイントにアクセスできないよう、Host ヘッダーは localhost の名前に制限されます。リバースプロキシの背後で使用する場合は、MCP_ALLOWED_HOSTS を設定してください。
  • リバースプロキシの背後で使用する場合は、プロキシで Host ヘッダーを内部のアップストリーム名に固定し、その名前だけを MCP_ALLOWED_HOSTS に登録することをおすすめします。そうすれば、検証が公開ドメインに依存せず、ドメイン変更後も機能します。(@WinFuture23からのヒントです。)
  • **MCP_ALLOWED_HOSTS を設定していて、プラットフォームが HTTP ヘルスチェックを行う場合は、そのホスト名もリストに追加する必要があります。**Railway は Host: healthcheck.railway.app を送信し、Kubernetes のプローブは設定によってコンテナの IP アドレス経由でリクエストします。名前がリストにないと、ヘルスチェックは 403 を受け取り、プラットフォームはデプロイに問題があると判断します。
  • **/health はホスト検証の後、トークン検証の前にあります。**そのため、プラットフォームのヘルスチェックにトークンは不要です。さらに、MCP_ALLOWED_HOSTS に公開ドメインを設定していても、付属の Dockerfile にある HEALTHCHECK が引き続き機能するよう、/health は常に localhost、127.0.0.1、[::1] を受け入れます。一方、ヘルスチェックがコンテナの IP アドレスまたはサービス名経由でリクエストする場合は、その名前を MCP_ALLOWED_HOSTS に追加する必要があります。
  • ツール呼び出しごとの api_key は、モデルが書き込み先のテナントを自分で決められないよう、デフォルトで無効になっています(BB_ALLOW_API_KEY_OVERRIDE=1 で有効にできます)。

セキュリティポリシーの全文と脆弱性の報告方法については、SECURITY.md をご覧ください。

クレジットとライセンス

BuchhaltungsButler 向けの非公式なコミュニティ統合です。BuchhaltungsButler とは提携しておらず、同社によるサポートもありません。 Model Context Protocol に基づいています。MIT ライセンスの下で公開されています。

コメント

MCP は初めてですか?

プロトコルの概要から最初のサーバーの導入まで、よくある疑問にまとめて答えます。

AI アプリケーションが外部のツールやデータソースに統一的な方法で接続するためのオープンなプロトコルです。クライアントはモデルとの対話を担い、MCP サーバーはツール・リソース・プロンプトテンプレートを提供します。標準メッセージでやり取りするため、1 つのサーバーを複数のクライアントで再利用できます。