Beancount.io LogoBeancount.io

Beancount MCP:台帳をClaude、Cursor、あらゆるAIアシスタントに接続

約2分Mike ThriftMike Thrift
Beancount MCP:台帳をClaude、Cursor、あらゆるAIアシスタントに接続

Web BeancountがMCPサーバーを公開 — すでにお使いのClaude、Cursor、あらゆるAIツールから台帳と対話

あなたの会計データが、AIワークフローと出会う。コピー&ペーストなし。エクスポートなし。ただ尋ねるだけ。

本日、Web Beancountは Beancount MCP Server を発表します。これは、あなたのBeancount台帳を、Claude Desktop、Claude Code、Cursor、Windsurf、その他あらゆるMCP対応AIクライアントに直接接続できるようにするModel Context Protocol(MCP)エンドポイントです。パワーユーザーは初めて、すでに日常的に使っているAIツールの中から、会計に関する質問をしたり、BQLクエリを実行したり、さらには台帳ファイルを編集したりできるようになります。タブを切り替えることも、ワークフローを離れることもありません。

プレーンテキストのBeancountファイルは、単なるファイルであるからこそ強力です。しかし「前四半期に旅行でいくら使ったか?」に答えるには、依然としてBQLの構文を知り、ファイルの場所を把握し、結果をチャットにコピーする必要があります。Beancount MCPサーバーは、その手間を完全に取り除きます。

AIクライアントにBeancount MCPサーバーを設定すれば、次のことができます。

  • 「今日の私の純資産はいくら?」と尋ね、実際の台帳から引き出したリアルタイムの回答を得る
  • 先月の支出のサマリーを依頼し、AIにBQLクエリを書いてもらう
  • AIに取引の追加を指示し、その変更を台帳のgitリポジトリにコミットする様子を見る
  • エディタを離れることなく、あなたの .beancount ファイルを閲覧・読み取りする

このサーバーは台帳スコープです。各MCPセッションは、OAuth 2.1を使ってちょうど1つの台帳に対して認可されます。Claude Codeのようなクライアントは、認可フローを自動的に検出して完了します。手動でのトークン管理は不要です。あなたの台帳は、すでに存在している場所、すなわちWeb Beancountのバックエンドにとどまります。AIクライアントは構造化されたツール呼び出しを当社のサーバーに送り、サーバーはあなたに代わって台帳を読み取ったり編集したりして、結果を返します。MCPサーバー自体は、AIクライアント自身の会話が保持するもの以外は何も保存しません。

Beancount MCPサーバーは、本日よりすべてのWeb Beancountユーザーが利用できます。

はじめに

Beancount MCPサーバーは稼働しています。1分もかからずにAIクライアントに追加できます。

MCPサーバーのURL

https://beancount.io/api-gateway/mcp

Claude Code(推奨 — 完全なOAuth 2.1フロー、トークン不要)

claude mcp add --transport http beancount https://beancount.io/api-gateway/mcp

初回利用時、Claude Codeはブラウザウィンドウを開きます。そのブラウザのプロンプトで、接続する台帳を選択します。一度承認すれば、認証情報は自動的に更新されます。台帳を複数お持ちですか?別の名前でサーバーをもう一度追加し(claude mcp add --transport http beancount-business https://beancount.io/api-gateway/mcp)、そのプロンプトでもう一方の台帳を認可してください。

Claude Desktop / Cursor / Windsurf / Zed

サーバーをクライアントのMCP設定(claude_desktop_config.json など)に追加します。OAuth 2.1に対応したクライアントは、初回利用時に同じブラウザのプロンプトを開きます。そこで台帳を選択してください。

{
  "mcpServers": {
    "beancount": {
      "url": "https://beancount.io/api-gateway/mcp"
    }
  }
}

クライアントがまだOAuthフローに対応していない場合は、beancount.ioのアカウント設定から(1つの台帳にスコープされた)静的トークンを生成し、ヘッダーとして渡してください。

{
  "mcpServers": {
    "beancount": {
      "url": "https://beancount.io/api-gateway/mcp",
      "headers": { "Authorization": "Bearer <your-token>" }
    }
  }
}

Web Beancountのアカウントをお持ちでないですか?beancount.io で登録してください。あなたの台帳は、gitのプッシュ1回で手に入ります。

よくある質問

お客様向けFAQ

MCPとは何で、なぜBeancountにとって重要なのですか?

MCP(Model Context Protocol)は、AIアシスタントが外部のツールやデータソースを構造化された安全な方法で呼び出せるようにするオープン標準です。AIのためのUSBポートのようなものだと考えてください。AIが推測したり、データを貼り付けるようあなたに求めたりする代わりに、あなたのシステムに直接接続します。Beancountユーザーにとってこれは、AIクライアントが実際の台帳データを照会し、実際のファイルを読み取り、正確な編集を行えることを意味します。中身を推測するのではありません。

どのAIクライアントがBeancount MCPサーバーで動作しますか?

OAuth 2.1に対応したMCP互換クライアントであれば、そのまま動作します。Beancount MCPサーバーはPKCEを用いた完全なOAuth 2.1認可フローを実装しているため、Claude Codeのようなクライアントはサーバーの認可エンドポイントを自動的に検出し、サインインを促します。手動でのトークンのコピーや設定は不要です。アクセスを承認すれば、クライアントが認証情報の保存と更新を自動的に行います。

MCP + OAuth 2.1への対応が確認されているクライアントには、Claude Code CLI、Claude Desktop、Cursor、Windsurf、Zedがあります。MCPエコシステムの成長に伴い、OAuth 2.1 MCP仕様に従う新しいクライアントは、当社側での変更なしに動作します。

台帳はどうやって接続しますか?

OAuth 2.1に対応したクライアント(Claude Codeなど)の場合:

  1. Beancount MCPサーバーのURLをクライアントのMCP設定に追加します。
  2. クライアントがアクセスを認可するためにブラウザウィンドウを自動的に開きます。
  3. Web Beancountのアカウントでログインし、アクセスを許可したい台帳を選択します。
  4. 完了です。ここから先は、クライアントがトークンの保存と更新を処理します。

OAuth 2.1に対応していないクライアントの場合は、Web Beancountのアカウント設定から(1つの台帳にスコープされた)静的トークンを生成し、Authorization: Bearer ヘッダーとして渡してください。

これは、ダッシュボードの「Ask AI」チャット機能と同じものですか?

両者は同じ基盤となる台帳ツール(BQLクエリ、ファイルの読み書き)を共有しますが、MCPサーバーは別の入り口です。ダッシュボードのAsk AI機能は、Cloudflareを基盤とするClaude Codeサンドボックスを備えたホスト型のチャット体験です。MCPサーバーは、あなたが選んだ自分のAIクライアントから接続するプロトコルエンドポイントであり、より多くの制御、より多くのモデル、そして既存のワークフローとのより深い統合をもたらします。

AIは実際に私の台帳で何ができますか?

MCPサーバーは4つのツールを公開しています。

ツール機能
runBqlQueryBQL(Beancount Query Language)を実行し、残高、取引、勘定科目を照会する
listLedgerFiles台帳リポジトリのディレクトリ構造を閲覧する
readLedgerFiles.beancount ファイルやその他の台帳ドキュメントの内容を読み取る
editLedgerFilesアトミックなgitコミットでファイルを作成、更新、置換、または削除する

AIはこれらを組み合わせられます。ファイル構造を把握し、コンテキストのために関連ファイルを読み取り、あなたの質問に答えるためのBQLクエリを書き、あるいは編集を提案してコミットします。

AIは、私の知らないうちに台帳を変更できてしまいますか?

ファイルの編集には、AIクライアントが変更内容の説明を添えて editLedgerFiles を呼び出す必要があります。行儀のよいMCPクライアント(Claude Codeを含む)は、実行前にこれをあなたに提示します。編集は、何も書き込まずに正確な変更をプレビューする dry_run モードにも対応しているため、クライアントはまず差分を表示できます。そして、コミットされるすべての変更は、あなたの台帳のリポジトリにおける実際のgitコミットです。したがって、完全な監査証跡が残り、標準のgitツールで何でも元に戻せます。

私のデータは第三者に送信されますか?

あなたの台帳データは、(すでにあなたの台帳を管理している)Web Beancountのバックエンドを通じて流れ、構造化された結果としてAIクライアントに返されます。あなたが使うAIモデル(例えばClaude)は、他のコンテキストと同様にツールの結果を受け取ります。MCPサーバーによって保存されるデータは、AIクライアントの会話がすでに保持しているもの以外にはありません。

各トークンは台帳スコープ — それはどういう意味ですか?

MCPサーバーを認可するとき、アクセスを許可する台帳を選択します。そのセッションはその台帳にのみアクセスできます。複数の台帳をお持ちの場合は、別々のセッションを認可します。これにより影響範囲が限定されます。個人用台帳のセッションが、業務用台帳に触れることはできません。

MCPサーバーは、Favaのウェブ UIが稼働している必要がありますか?

いいえ。MCPサーバーは、Web Beancountのインフラが管理する内部のFava APIと通信します(Favaは、あなたのbeancount.io台帳を支えるウェブインターフェースです)。FavaのUIを開いておいたり、アクセス可能にしておいたりする必要はありません。

MCPアクセスを取り消すとどうなりますか?

進行中のMCPセッションは、次のツール呼び出しで401エラーを受け取ります。OAuth 2.1に対応したクライアントは、自動的に再認可を試み、再度のログインを促します。

内部の仕組み

技術的に興味のある方へ — サーバーがどのように作られているか。

AIツールごとに独自のAPI/プラグインを作るのではなく、なぜMCPなのですか?

MCPは台頭しつつある標準であり、主要なAIエディタのすべてですでにサポートされています。準拠したMCPサーバーを1つ作れば、Claude、Cursor、Windsurf、そして来四半期に登場する何であれ、個別の統合を維持するのに比べて、エコシステム全体との互換性を一度に得られます。プロトコルが検出、ツールスキーマ、ストリーミングを担い、私たちはドメインロジックに集中します。

なぜ静的なAPIキーではなくOAuth 2.1なのですか?

PKCEを用いたOAuth 2.1は、MCP仕様がリモートサーバー向けに推奨しているものであり、Claude Codeのようなクライアントがネイティブに実装しているものです。実用上の利点は、ユーザーがトークンに一切触れないことです。クライアントは当社の .well-known/oauth-protected-resource メタデータエンドポイントを通じて認可サーバーを検出し、PKCEを完了し、更新を自動的に管理します。静的トークンは、完全なフローをまだ実装していないクライアントのためのフォールバックとして引き続きサポートされます。

なぜSSEやstdioトランスポートではなくStreamable HTTPなのですか?

Streamable HTTPは、HTTPS上のリモートサーバー向けに設計されたMCPトランスポートです。stdioはローカルプロセス向けです。SSE(より古いMCPトランスポート)は、Streamable HTTPを優先して非推奨になりつつあります。当社のユーザーは、サーバーと同じ場所にないAIクライアントから接続するため、Streamable HTTPが正しく、将来を見据えた選択です。

なぜMCPセッションはステートレス(sessionIdGenerator なし)なのですか?

私たちは、各リクエストを完全にステートレスにするために sessionIdGenerator: undefined を設定しています。ツール呼び出しの間に、サーバー側のセッション状態が割り当てられたり保持されたりすることはありません。これはStreamable HTTP仕様のステートレスモードに一致し、セッションアフィニティなしでサーバーを水平にスケールできるようにします。ツールのコンテキスト(台帳の識別情報、Fava APIクライアント)は、検証済みのOIDCトークンからリクエストごとに再構築されます。

台帳アクセスの検証はどのように機能しますか?

OIDCトークンの検証後、resolveLedgerAccess は、認証されたユーザーが要求された台帳に実際にアクセス権を持っていることをFava APIを通じて確認します。これにより、ある台帳の有効なトークンが、別のユーザーの台帳を探るために使われるのを防ぎます(署名付きトークンの上に重ねる多層防御)。

editLedgerFiles はどこにコミットしますか?

これはFava APIの changeLedgerFiles を呼び出し、台帳のGiteaリポジトリに AI edit: <description> というメッセージでgitコミットを作成します。この説明は、AIが記入する description フィールドから取られ、行儀のよいMCPクライアントでは実行前にユーザーに提示されます。

editLedgerFiles の dry_run オプションとは何ですか?

dry_run: true は、すべてのファイル操作を検証し(ファイルの存在を確認し、str_replace の古い文字列がちょうど1回一致することを確かめ)、実際にgitへ書き込むことなく、コミットされる内容のプレビューを返します。これは、コミット前にユーザーに差分を表示したいAIクライアントにとって便利です。

AIクライアントから見えるエラーの形式はどのようなものですか?

ツールのエラーは { isError: true, content: [{ type: "text", text: "..." }] } として返されます。これはMCP SDKの構造化されたエラー形式です。AIクライアントはエラーメッセージをテキストとして受け取り、どう処理するか(再試行、ユーザーへの報告など)を判断できます。HTTPレベルの認証失敗(401)には、OAuth保護リソースのメタデータを指す WWW-Authenticate ヘッダーが含まれるため、準拠したクライアントは認可フローを自動的に再開できます。

すべての投稿に戻る