billy-mcp

billy-mcp — Claude と AI アシスタント向け Billy（billy.dk）MCP サーバー

Claude、Cursor、VS Code、その他のMCP互換AIアシスタントを、デンマークの会計プラットフォームであるBilly（billysbilling）に接続します。 請求書の作成、仕訳の記帳、勘定残高の確認、銀行明細行の照合、領収書の添付が可能です。人間による承認を必須とする書き込み保護機能を内蔵しているため、AIが承認なしに記帳することはありません。

Billy会計 · Billy.dk API · デンマークの簿記（bogføring/regnskab） · AI簿記エージェント · Model Context Protocol サーバー · Claude Desktop連携

何ができますか？

AIアシスタントに、次のように依頼できます。

• 「Acme ApS宛てに、コンサルティング10時間分、1.200 DKK、支払期限14日後の請求書を作成して」
• 「今四半期の勘定科目5211の残高はいくら？」（実際の記帳に基づく試算表）
• 「先月の給与を仕訳として記帳して。下書きにしておいて、承認は私がする」
• 「重複した仕訳34件を取り消して」（1回の呼び出しで、1回の承認を行い、項目ごとの結果を取得）
• 「この領収書PDFをアップロードして、仕訳#67に添付して」
• 「支払期限を過ぎていて未払いの請求書はどれ？」

請求書、仕入先請求書、連絡先、製品、銀行支払い、手動仕訳（仕訳帳の取引）、記帳、試算表、銀行照合、ファイル添付、サンドボックス化されたバッチスクリプトツール、その他すべてに対応する生APIのエスケープハッチを網羅する40種類のツールを提供します。

クイックスタート

1. Billyのアクセストークンを取得する

mit.billy.dkにログインし、Settings → Access tokens → Create access tokenを選択します。トークンは会社ごとに発行され、有効期限はありません。

2. MCPクライアントに追加する

Claude Desktop（claude_desktop_config.json）／Cursor／JSON設定を使用する任意のホスト：

{
  "mcpServers": {
    "billy": {
      "command": "npx",
      "args": ["-y", "billy-mcp"],
      "env": {
        "BILLY_ACCESS_TOKEN": "<your token>"
      }
    }
  }
}

Claude Code（CLI）：

claude mcp add billy -e BILLY_ACCESS_TOKEN=<your token> -- npx -y billy-mcp

VS Code（.vscode/mcp.json）：

{
  "servers": {
    "billy": {
      "command": "npx",
      "args": ["-y", "billy-mcp"],
      "env": { "BILLY_ACCESS_TOKEN": "${input:billy-token}" }
    }
  }
}

これだけです。クローンやビルドは不要です。npxが公開済みパッケージを取得します。

ソースから実行する（開発用）

git clone https://github.com/thourum/billy-mcp.git
cd billy-mcp
npm install
cp .env.example .env      # paste your token
npm run dev               # run over stdio
npm run inspector         # try tools in the MCP Inspector UI

書き込み保護 — 実際の財務データも安全

すべての書き込み（作成／更新／承認／取消／支払い／アップロード）は、BILLY_WRITE_MODEによって制御されます。

モード	動作
read-only	書き込みツールは登録されません。生のリクエストもGET以外は拒否されます
confirm （デフォルト）	書き込みのたびに処理が一時停止し、ペイロード全体を含むネイティブの承認ダイアログ（MCP elicitation）があなたに表示されます。AIが自分の書き込みを承認することはできません
full	承認なしで書き込みを実行します

フェイルクローズ方式です。MCPホストが確認ダイアログに対応していない場合、confirmモードでは実行せず、代わりに手順を表示して書き込みをブロックします。請求書の承認、仕訳の取消、銀行支払いなどの取り消し不能な操作には、ホストが独自の保護策を追加できるよう、destructiveHintのフラグも設定されています。承認しない、ダイアログを閉じる、またはチェックボックスを選択しない場合、何も記帳されません。

環境変数

変数	必須	説明
BILLY_ACCESS_TOKEN	はい	Billy APIアクセストークン（X-Access-Tokenとして送信）
BILLY_WRITE_MODE	いいえ	read-only、confirm（デフォルト）、またはfull
BILLY_ORGANIZATION_ID	いいえ	トークンが1社に紐付いている場合は自動解決されます
BILLY_BASE_URL	いいえ	デフォルトはhttps://api.billysbilling.com/v2です
BILLY_LOCALE	いいえ	en_US、da_DK、fr_FR、nl_NL、de_DE

ツール

ツール一覧（40）

組織と連絡先 — get_organization、list_contacts、get_contact、create_contact、update_contact、list_contact_persons、create_contact_person

製品 — list_products、get_product、create_product、update_product

請求書 — list_invoices、get_invoice、create_invoice（明細を埋め込み、下書きまたは即時承認）、approve_invoice、delete_invoice

仕入請求書（経費） — list_bills、get_bill、create_bill

支払い — create_bank_payment（請求書／仕入請求書を支払済みにする）、list_bank_payments、list_balance_modifiers

仕訳（仕訳帳） — create_daybook_transaction（クライアント側で借方／貸方の残高を検証し、冪等性キーによる安全な再試行に対応）、void_daybook_transaction、batch_void_daybook_transactions（複数の仕訳を無効化し、承認は1回）、list_daybook_transactions、list_daybooks

レポートと照合 — get_account_balances（試算表／転記に基づく勘定科目別残高）、list_postings、list_transactions、list_accounts、get_account、list_bank_lines、list_bank_line_matches

ファイルと添付ファイル — upload_file（pdf/jpg/png/gif）、attach_file（請求書／仕入請求書／仕訳へのリンク）、list_files、list_attachments

パワーツール — execute_script（サーバー側で強制される変更ログとdry_runを備えた、サンドボックス化されたJSバッチ実行ツール）、billy_raw_request（Billy v2の任意のエンドポイント）

人間だけでなく、LLM エージェント向けに設計

• デフォルトでコンパクトな応答（トークンを約90％削減）。完全なペイロードを取得するにはverbose: trueを指定します
• appliedFiltersによる透明性：Billyは不明なクエリパラメーターを黙って無視します。すべての一覧表示ツールは、どのフィルターがサーバー側で適用され、どれがクライアント側で適用されたかを報告するため、エージェントが「フィルターが無視された」ことを「結果がない」と誤認することはありません
• 事前検証：貸借不一致の仕訳は、承認が要求される前に、通貨ごとの借方／貸方合計とともにクライアント側で拒否されます
• 冪等な再試行：仕訳のidempotencyKeyにより、タイムアウト後の重複を安全に防ぎます
• 1回の承認でバッチ処理：execute_scriptはループ（例：34件の無効化）を実行し、スクリプトが途中で失敗した場合も完全な監査ログを返します

FAQ

これはBillyの公式インテグレーションですか？ いいえ。Billyの公開REST API v2を使用するコミュニティプロジェクトです。

Billyの無料プランで動作しますか？ はい。mit.billy.dkでアクセストークンを作成できるアカウントであれば、どれでも利用できます。

AIが勝手に支払いを実行することはありますか？ デフォルトのconfirmモードでは、モデルが操作できないダイアログであなたが承認をクリックしない限り、書き込みは実行されません。分析のみを行う場合は、read-onlyを使用してください。

どのAIアプリに対応していますか？ 標準入出力を介してModel Context Protocolを話すアプリであれば、どれでも対応しています。Claude Desktop、Claude Code、Cursor、Windsurf、VS Code（GitHub Copilot）、Zedなどが含まれます。

開発

npm run typecheck   # tsc --noEmit
npm run build       # compile to dist/
npm run inspector   # interactive tool testing

技術スタック：TypeScript、MCP TypeScript SDK v2、Zod v4スキーマ。Billy APIのリファレンスはdocs/billy-api.mdに複製されています。

ライセンス

MIT

---

キーワード：Billy MCP サーバー、billy.dk API、billysbilling連携、デンマークの会計AI、簿記の自動化、会計AI、Claude会計、MCP会計サーバー、デンマークのAI簿記、請求API。