moneybird-mcp

Moneybird 会計 API 用の Model Context Protocol サーバーです。Moneybird を一連の MCP ツールとして公開するため、Claude などのアシスタントが連絡先の検索、請求書の読み取り、銀行取引の確認、作業時間の記録、管理台帳からのレポート取得を行うことができます。アクセスは書き込みを有効にするまで読み取り専用です。ツールは個別に有効化できるツールセットにグループ化されており、クライアントは Moneybird のレート制限内に収まるように自身のリクエストのペースを調整します。ローカルクライアントには stdio、リモートクライアントには Streamable HTTP で通信します。

クイックスタート

サーバーをクライアントに登録します。Claude Code の場合:

claude mcp add moneybird -- npx -y moneybird-mcp serve

次に、アシスタントに接続するよう依頼します。サーバーは認証情報なしで起動し、connect_moneybird ツールを公開します。これは、ブラウザで Moneybird のトークンページを開き、そこで作成したトークンの入力を求め、検証し、管理台帳を選択して保存します — 会話から離れることなく。

これには MCP の情報引き出し (elicitation) をサポートするクライアントが必要です。それが利用できない場合は、同じセットアップをターミナルで実行できます:

npx moneybird-mcp login

同じ手順を対話形式で案内し、結果を ~/.config/moneybird-mcp/credentials.json に保存します。

実際に依存する前に、すべてが正しく解決されることを確認してください:

npx moneybird-mcp status

status は、有効なツールセット、書き込み・削除の設定、認証情報の取得元、トークンがアクセスできる管理台帳を表示します。Moneybird に到達できない場合は非ゼロの終了コードで終了します。

Related MCP server: kalender.digital MCP Server

認証

Moneybird にはトークンを取得する方法が 2 つあり、このサーバーは両方に対応しています。どちらも完全に手間のかからない方法ではありません。Moneybird は Dynamic Client Registration も PKCE も実装していないため、トークンの作成やアプリケーションの登録を省略できるフローは存在しません。これはサーバーの問題ではなく、Moneybird API の制限です。connect_moneybird ツールが行うのは、その 1 つのステップ以外のすべての手順を取り除くことです — 適切なページを開き、結果を取得してくれます。

個人 API トークン。 自分で https://moneybird.com/user/applications/new で作成し、必要なスコープにチェックを入れて、moneybird-mcp login に貼り付けます。最も簡単な方法です。スコープは作成時に固定され、Moneybird は現在これらのトークンを失効させません — つまり、自動的にローテーションすることもできません。パスワードのように扱ってください。

OAuth アプリケーション。 同じ場所でアプリケーションを登録します。次に:

export MONEYBIRD_CLIENT_ID=...
export MONEYBIRD_CLIENT_SECRET=...
npx moneybird-mcp login --oauth

サーバーは Moneybird の認可ページを開き、http://127.0.0.1:51739/callback へのリダイレクトを受け取り、コードを交換します。Moneybird はリダイレクト URI を完全一致で照合するため、その URI はアプリケーションにそのまま登録されている必要があります。--port で別のポートを選択するか、--oob でリダイレクトの代わりにブラウザにコードを表示させることができます — ループバックリスナーを開けない場合に便利です。OAuth トークンは Moneybird 側で失効させることができ、有効期限が設定されている場合は自動的に更新されます。

プロンプトを一切表示せずにトークンを保存するには、たとえばプロビジョニングスクリプト内で:

npx moneybird-mcp login --token "$MONEYBIRD_TOKEN"

moneybird-mcp logout は保存されたファイルを削除します。OAuth 認証情報の場合、認可自体は失効させません — 失効は Moneybird 側で行ってください。

スコープ、更新動作、正確なフローについては docs/authentication.md を参照してください。

設定

設定は環境変数から取得されます。CLI フラグがそれを上書きします。

環境変数

コマンド

フラグ

ツールセット

ツールは Moneybird 自身のドメインごとにグループ化されています。デフォルトでは 5 つが有効で、残りの 4 つはオプトインです。

明示的に設定するか、デフォルトに追加するか、デフォルトから差し引きます:

moneybird-mcp serve --toolsets core,invoicing     # exactly these two
moneybird-mcp serve --toolsets all                # everything
moneybird-mcp serve --toolsets reports            # exactly reports
moneybird-mcp serve --toolsets -banking,-time     # the defaults minus two

リスト内のどこにあっても、-name エントリがある場合は、リストがゼロからではなくデフォルトから始まることを意味します。all は他のすべてより優先されます。不明な名前はエラーになり、黙って無視されることはありません。

ツールごとの完全な一覧は docs/tools.md にあります。または moneybird-mcp tools を実行してください。

安全モデル

すべてのツールは 3 つのアクセス層のいずれかを宣言し、サーバーは現在の設定で許可されたツールのみを登録します。登録されていないツールはモデルから見えないため、誤って呼び出されたり、言葉巧みに存在させられたりすることはありません。

• read — 常に登録されます。

• write — データを作成または変更します。--allow-write または MONEYBIRD_ALLOW_WRITE=true が必要です。

• destroy — --allow-delete かつ --allow-write が必要です。--allow-delete だけでは何も行いません。

削除には書き込みとは別のゲートが設けられています。この2つの障害モードは比較できないためです。誤った書き込みは修正できるレコードを残しますが、削除や顧客に送信した請求書は、API が取り消せるものではありません。アシスタントが請求書を下書きできるように書き込みを有効にしても、帳簿を削除できるようにもなるべきではありません。したがって、destroy 層は、削除と、連絡先へのドキュメント送信など、現実には取り消し不能な呼び出しの両方をカバーします。

読み取り専用がデフォルトです。必要な最小限だけを有効にしてください:

claude mcp add moneybird --env MONEYBIRD_ALLOW_WRITE=true -- npx -y moneybird-mcp serve

クライアント設定

Claude Code

claude mcp add moneybird -- npx -y moneybird-mcp serve

書き込みアクセスとより広いツール選択が必要な場合:

claude mcp add moneybird \
  --env MONEYBIRD_ALLOW_WRITE=true \
  --env MONEYBIRD_TOOLSETS=all \
  -- npx -y moneybird-mcp serve

Claude Desktop

サーバーを claude_desktop_config.json に追加します:

{
  "mcpServers": {
    "moneybird": {
      "command": "npx",
      "args": ["-y", "moneybird-mcp", "serve"],
      "env": {
        "MONEYBIRD_ALLOW_WRITE": "true"
      }
    }
  }
}

このファイルは macOS では ~/Library/Application Support/Claude/claude_desktop_config.json、Windows では %APPDATA%\Claude\claude_desktop_config.json にあります。編集後、アプリを再起動してください。

任意の stdio クライアント

このサーバーはプレーンな stdio MCP サーバーです。moneybird-mcp serve を実行し、stdin と stdout で JSON-RPC をやり取りします。診断情報は stderr に出力され、stdout には決して出力されません。

{
  "command": "npx",
  "args": ["-y", "moneybird-mcp", "serve"],
  "env": {
    "MONEYBIRD_API_TOKEN": "..."
  }
}

認証情報をディスクに保存したくない場合は、クライアントの env ブロックで MONEYBIRD_API_TOKEN を設定してください。これは credentials.json 内のすべての値より優先されます。

Docker とセルフホスティング

docker build -t moneybird-mcp .
docker run --rm -p 3000:3000 -e MONEYBIRD_API_TOKEN=... moneybird-mcp

イメージはデフォルトで 0.0.0.0:3000 の HTTP トランスポートを使用し、/mcp に加えて認証なしの /healthz を公開します。認証なしでパブリックなアドレスに公開しないでください。

docs/hosting.md では、3つの HTTP 認証モード、マルチテナントの passthrough デプロイ、リバースプロキシに関する注意点、リモートクライアントの接続について説明しています。

レート制限

Moneybird は IP あたり5分間に150リクエスト、/reports エンドポイントでは 5分間に50リクエスト を許可しています。クライアントは両方のバジェットについて独自のスライディングウィンドウカウンターを維持し、これを超えるリクエストは遅延されるため、通常の使用では 429 は発生しません。Moneybird がそれでも 429 を返した場合、クライアントは Retry-After を尊重し、それ以外の場合はフルジッター付きの指数バックオフを MONEYBIRD_MAX_RETRIES 回の試行まで行います。

バジェットはトークン単位ではなく IP 単位です。1つの egress アドレスの背後にある複数のインスタンスはこれを共有するため、ローカルカウンターは互いを認識できません。デプロイメントの規模はこれに応じて設計してください。

開発

npm install
npm run build      # before typecheck: the docs generator imports the built output
npm run typecheck
npm test
npm run format

docs/tools.md はツール定義から生成されます。ツールを追加または変更した後は再生成してください:

npm run docs:tools

spec/endpoints.json は Moneybird が公開している操作リストを固定し、テストはツールが呼び出すすべてのパスをそれと照合します。Moneybird が API 変更をリリースしたら更新してください:

npm run spec:refresh
npm test

更新後にエンドポイントテストが失敗した場合、ツールが依存するルートが移動したか撤回されたことを意味します。

コントリビューション

Issue と pull request は https://github.com/HalloSouf/moneybird-mcp で歓迎します。pull request を開く前に、npm run typecheck、npm test、npm run format:check を実行してください。CI は Node 20 と 22 で同じチェックを実行します。

ライセンス

MIT. LICENSE を参照してください。