MCP Server for YNAB

YNAB 向け MCP サーバー

予算について質問しましょう。 Claude、Codex、Cursor、その他の MCP クライアントを YNAB に接続して、実際のお金の状況について回答を得られます。月の予算の進み具合、予算超過の項目、サブスクリプションの実際の費用などを確認できます。

YNAB_API_KEY=your_token uvx mcp-server-for-ynab smoke

デフォルトでは読み取り専用です。 YNAB_ALLOW_WRITES=1 を設定しない限り、書き込みツールは登録されないため、アシスタントに表示されることはなく、明示的に有効にするまでは予算が変更されることもありません。有効にした場合、書き込みを行うたびに変更前の状態が記録され、元に戻すことができます。

 MCP サーバーは、YNAB API をツールとして公開し、さらに、API を1回呼び出すだけでは回答できない質問に答えるための拡張ツールを追加します。予算の健全性、整理が必要な項目、支出分析、定期的な請求などに対応します。

クイックスタート

1. YNAB トークンを取得する

app.ynab.com/settings/developer で個人用アクセストークンを生成します。

また、uvx を提供する uv も必要です。

curl -LsSf https://astral.sh/uv/install.sh | sh   # macOS and Linux
brew install uv                                   # macOS with Homebrew
winget install --id=astral-sh.uv -e               # Windows

両方が動作することを確認します。クローンする必要はありません。uvx がパッケージを取得し、一時的な環境で実行します。

YNAB_API_KEY=your_token uvx mcp-server-for-ynab smoke

smoke は設定とツールの登録を検証してから終了します。smoke: app created, 62 tools registered と表示されるはずです。

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

クライアント	セットアップ
Claude Code	コマンド 1 つ
Claude Desktop	設定ファイル
Cursor	ワンクリックリンク
VS Code（GitHub Copilot）	コマンド 1 つ
Codex CLI	コマンド 1 つ
Gemini CLI	コマンド 1 つ
Windsurf、Zed など	汎用 stdio 設定
MCP Inspector	デバッグ

よく使われる 2 つの方法をご紹介します。

Claude Code — プラグインをインストールします。プラグインには独自の MCP 設定が含まれています。

/plugin marketplace add hs737/mcp-server-for-ynab
/plugin install mcp-server-for-ynab@mcp-server-for-ynab

プラグインを使いたくない場合は、サーバーを直接登録することもできます。

claude mcp add --env YNAB_API_KEY=your_ynab_token --transport stdio --scope user \
  ynab -- uvx mcp-server-for-ynab stdio

Claude Desktop、Cursor、Windsurf など — クライアントの MCP 設定ファイルに貼り付けます。

{
  "mcpServers": {
    "ynab": {
      "command": "uvx",
      "args": ["mcp-server-for-ynab", "stdio"],
      "env": {
        "YNAB_API_KEY": "your_ynab_token",
        "YNAB_PLAN_ID": "your_plan_id"
      }
    }
  }
}

YNAB_PLAN_ID は省略可能ですが、設定することをおすすめします。設定すれば、リクエストで予算名を指定する必要がなくなります。設定ファイルの場所やトークンを設定ファイルに含めない方法など、クライアントごとの詳しい手順はクライアントのセットアップをご覧ください。

バンドルに対応したデスクトップホスト — 最新リリースから .mcpb ファイルをダウンロードして開きます。ホストはフォームでトークンの入力を求め、OS のキーチェーンに保存します。そのため、編集する設定ファイルはなく、トークンが平文で保存されることもありません。書き込みを有効にするかどうかは、チェックボックスで設定できます。

Docker

公開済みのイメージは linux/amd64 と linux/arm64 で利用できます。サーバーは stdin と stdout を介して MCP 通信を行うため、-i を付けて接続した状態で実行します。公開するポートはありません。

docker run -i --rm -e YNAB_API_KEY=your_ynab_token \
  ghcr.io/hs737/mcp-server-for-ynab

または、クローンから自分でビルドすることもできます。

docker build -t mcp-server-for-ynab .
docker run -i --rm -e YNAB_API_KEY=your_ynab_token mcp-server-for-ynab

書き込みを有効にする場合は、履歴用のボリュームをマウントしてください。マウントしないと、元に戻すための記録が --rm によって破棄されます。

docker run -i --rm -e YNAB_API_KEY=your_ynab_token -e YNAB_ALLOW_WRITES=1 \
  -v ynab-mcp-history:/home/app/.mcp-server-for-ynab mcp-server-for-ynab

3. 質問してみる

すべての口座を合わせた現在の現金残高は？

うまく動けば、準備完了です。動作しない場合はトラブルシューティングをご覧ください。よくある原因は、クライアントが PATH 上で uvx を見つけられないことです。

質問できること

読み取り専用で、そのまま使えます。

質問	使用するツール
「今月の予算はどんな状況ですか？」	overview_month_health
「すべての口座を合計した現金残高はいくらですか？」	overview_cash_position
「まだカテゴリを設定していない取引はどれですか？」	triage_uncategorized
「承認待ちの項目はありますか？」	triage_unapproved
「予算超過しているカテゴリはどれで、いくら超過していますか？」	analysis_overspent_categories
「今月、資金が割り当てられない目標はどれですか？」	analysis_target_funding_gaps
「予定されている取引のうち、リスクがあるものはありますか？」	analysis_upcoming_scheduled_risks
「過去1年間、この受取人にいくら使いましたか？」	bookkeeping_transaction_history
「実際に支払っているサブスクリプションは何ですか？」	analysis_recurring_charges
「この口座は明細書と一致していますか？　一致しない原因は何ですか？」	reconcile_preview
「銀行のCSVはこちらです。両方で不足しているものは何ですか？」	transactions_match_statement
「口座に残ったまま、取引として計上されていないカードの利用枠はありますか？」	triage_pending_imports

YNAB_ALLOW_WRITES=1 の場合：

先週の未分類の取引をカテゴリ分けして、変更内容を見せてください。

エージェントがカテゴリを設定し、history_list ですべての書き込みと変更前の値を確認できます。history_revert で、いずれの変更も取り消せます。

エージェントは、まず overview_available_tools を実行すると効果的です。このツールは、現在のツールカタログをカテゴリ別に返します。全体像については、ツール一覧をご覧ください。

ガイド付きワークフロー

サーバーには7つのプロンプトが付属しており、ほとんどのクライアントではスラッシュコマンドとして表示されます。ツール一覧を先に読む必要のない、作業の出発点として利用できます。月次レビュー、週次トリアージ、カテゴリ設定と承認、サブスクリプションの監査、現金残高の確認、レビューと取り消し、複数月にわたる予算監査が含まれます。

4つのリソース（ynab://guide/*）には、YNAB のメソッド、書き込みの安全性に関するルール、使用するツールの選び方、クレジット口座の動作が記載されています。これらは必要に応じて取得されるため、クライアントが要求するまでは費用がかかりません。

設定

変数	必須	説明
YNAB_API_KEY	はい	YNAB の個人用アクセストークン
YNAB_PLAN_ID	推奨	デフォルトのプラン ID。多くのツールで plan_id を省略できます
YNAB_ALLOW_WRITES	いいえ	書き込みツールを登録します。未設定の場合は読み取り専用です
YNAB_HISTORY_PATH	いいえ	書き込み履歴ファイル。デフォルトは ~/.mcp-server-for-ynab/history.jsonl です
YNAB_RATE_LIMIT_PER_HOUR	いいえ	クライアント側のリクエスト上限。デフォルトは YNAB の上限200件のうち 190 件です
YNAB_RATE_WARN_THRESHOLD	いいえ	残りのリクエスト数がこの値になったときに警告します。デフォルトは 50 です
LOG_LEVEL	いいえ	ログの詳細度。デフォルトは INFO です

これらは、MCP クライアントの env ブロックで設定してください。ローカル開発では、.env.example を .env にコピーして値を入力します。

レート制限

YNAB では、トークンごとに1時間あたり200件のリクエストが許可されます。1つの拡張ツールで複数のリクエストを消費することもあります。サーバーは直近1時間の使用状況を追跡し、YNAB の上限をわずかに下回るところで停止します。そのため、ワークフローの途中で429エラーが発生するのではなく、ローカルの上限に達したことが明確に報告されます。

各ツールの応答には、HTTP API が X-RateLimit-Remaining を返すのと同じように、requests_used_this_hour と requests_remaining が含まれます。エージェントはすでに確認できる数値に基づいてリクエストのペースを調整でき、その数値を尋ねるために、本来行わないはずのリクエストを使う必要はありません。overview_request_budget は上限、時間枠、上限を使い切った後に再び利用可能になる時刻を追加で返します。ping はサーバーが稼働しているかどうかに答えます。どちらもリクエストを消費しません。

上限はアクセストークンに適用されるため、ご自身の YNAB アプリも同じ枠を消費します。ここで示される件数は、このサーバーが使用した数なので、YNAB 側に残っている件数より少ない場合があります。レート制限エラーにはその旨が記載され、再び利用可能になる時刻が絶対時刻と待ち時間の両方で示されるため、スケジュールされた再試行が早すぎることはありません。

ツールファミリー

読み取り専用ツールが 62 個、書き込みを有効にすると 84 個、さらにガイド付きプロンプトが 7 個、参照リソースが 4 個あります。

ファミリー	種類	目的
overview	enriched	予算の健全性スナップショットと全体像の把握
triage	enriched	取引の整理キュー
bookkeeping	enriched	分類の提案、メモの補助、履歴
analysis	enriched	支出超過、資金不足、予定されているリスク、カードへの資金割り当て、複数月の監査
reconcile	enriched	明細の比較、銀行のエクスポートデータとの照合、照合の完了
history	enriched	このサーバーが行った書き込みの確認とロールバック
changes	enriched	指定した server_knowledge 値以降の変更内容
user	raw	YNAB のユーザー情報
plans	raw	プランと設定の読み取り
accounts	raw	アカウントの読み取りと作成
categories	raw	カテゴリーとカテゴリーグループ
months	raw	月単位の予算データ、複数月の範囲、一括割り当て
payees	raw	受取人の管理
payee_locations	raw	受取人の地理情報メタデータ、専門性が高く優先度は低め
transactions	raw	取引の CRUD とインポートのトリガー
scheduled_transactions	raw	予定取引の管理
money_movements	raw	資金移動データとカテゴリー間の資金移動

raw ツールは YNAB エンドポイントをほぼそのまま反映したものです。正確な読み取りと、ほとんどの書き込みに使用します。enriched ツールは複数の読み取りをまとめて 1 つの回答を返します。全体像の把握、調査、分析に使用します。すべてのツールには read または write のラベルが付いており、名前と説明に明記されていない限り、enriched ツールが書き込みを行うことはありません。

大量の JSON を読み込まずに、予算データを多く読み取る

実際のプランの 1 か月分は約 60 KB の JSON になります。YNAB が、非表示のカテゴリーも含め、すべてのカテゴリーの目標フィールドを返すためです。その方法で 1 年分を確認すると、コンテキストウィンドウに収まりません。

• months_get と categories_list は compact=true を指定でき、カテゴリーごとに 30 個ではなく 6 個のフィールドを返します。サイズは約 4 分の 1 です。
• months_range は、指定した全期間をカテゴリー別・月別の 1 つのマトリックスとして返すため、21 か月分の確認を 21 回ではなく 1 回の呼び出しで行えます。
• category_groups_summary_by_month は同じことをグループ単位で行います。「これは健全か」といった質問の大半が対象とするのは、この単位です。
• changes_since は、指定した server_knowledge 値以降の変更内容を報告します。そのため、ユーザーが予算を編集した後の再確認は、小さな呼び出し 1 回で済みます。

範囲ツールでも月ごとに YNAB リクエストを 1 回消費します。範囲を指定するエンドポイントはありません。そのため、各ツールにはリクエストのコストが記載されており、期間は最大 36 か月に制限されています。

詳細はこちら：ツール一覧

書き込みツール

書き込みツールは、明示的に有効にしない限り登録されません。

YNAB_ALLOW_WRITES=1

これを設定しない場合、サーバーは読み取り専用となり、書き込みツールは tools/list に表示されません。エージェントは認識できないツールを呼び出せません。これは意図的な設計です。このサーバーには実際の金融記録を変更できる認証情報が保存されているため、実行時に呼び出しを拒否するだけでは、その機能があることを知らせてしまいます。

すべての書き込みが記録され、そのほとんどは元に戻せます

書き込みが有効な場合、書き込みのたびに、その直前の状態が記録されます。 YNABには履歴エンドポイントがないため、上書きされた値を復元する方法はこれしかありません。

ツール	目的
history_list	最近の書き込みを新しい順に表示し、それぞれに取り消し可能かどうかを示します
history_show	1件のエントリーの全情報を、変更前の状態も含めて表示します
history_revert	1件の書き込みを取り消します
history_revert_to	指定したエントリー時点の状態までプランを巻き戻します

history_revert_toは、指定したエントリーより後の変更をすべて、新しいものから順に取り消します。同じレコードへの変更が重なっている場合、逆順でのみ正しく反映されるためです。 取り消し操作自体も記録されるため、取り消しをさらに取り消すこともできます。

元に戻せない操作。 YNABには、アカウント、カテゴリー、カテゴリーグループ、または受取人を削除するルートがないため、これらを作成すると元に戻せません。こうした操作は、理由とともに取り消し不可として記録されます。ロールバック時には、黙ってスキップするのではなく、blockedに表示されます。未完了のロールバックを成功したと報告するより、何が残ったかを伝えるほうが重要です。再作成された取引には新しいIDが割り当てられ、銀行インポートとのリンクも失われます。

書き込みは推測ではなく、検証されます

値を変更するツールは、変更後に値を再読み込みし、verificationブロックを返します。200応答は成功の証明ではありません。YNABはカテゴリー更新ルートでbudgetedを受け付け、200を返すものの、その値を無視します。これを検出するのが検証です。

プランの適用と資金の移動

YNABのAPIでは、1回に割り当てられるのは1カテゴリーの1か月分です。そのため、1か月分のプランを適用するには、35回の個別の書き込みと35件の履歴エントリーが必要になります。

• months_assign_manyは1回の呼び出しで1か月分全体を適用し、1件のエントリーとして記録するため、その判断をまとめて取り消せます。
• money_moveは、2つのカテゴリー間、または「割り当て準備金」と各カテゴリー間で利用可能な資金を移動します。現在の金額を読み取って計算するため、繰り越し残高を割り当て済み金額と取り違えません。
• reconcile_applyは、照合を完了します。合意済みの取引を1回の一括呼び出しで照合済みにし、残額を解消する調整を1件のエントリーとして記録するため、両方をまとめて取り消せます。

どちらの割り当てツールも合計額の代わりにadjust_byを指定できます。ツール側で現在の金額を読み取り、取り消し時に復元する値を記録するため、事前に現在の金額を読み取らずに「このカテゴリーに4,500ドルを追加する」と指定できます。これは原子的な差分ではありません。YNABのAPIには差分指定も条件付き書き込みもないため、金額を読み取って合計額を書き込みます。その2回の呼び出しの間にアプリで編集が行われると、その変更は上書きされます。これにexpected_budgetedを併せて渡すと、読み取った金額が想定と異なる場合は書き込みが拒否されます。そのため、すでに金額が変わっている値に基づいて処理しようとすると、上書きせずに停止します。これは書き込み前のチェックであり、書き込みの前提条件ではありません。YNABのルートにはその間の競合を防ぐ手段がないため、読み取りから書き込みまでの間隙は残ります。 いずれの場合も、応答にはprevious_budgeted、budgeted、changeが含まれるため、再読み込みせずに書き込みを確認できます。

YNABにはトランザクション境界がないため、どの操作も原子的ではありません。それぞれ、適用された内容と失敗した内容を報告します。money_moveが一部だけ書き込まれた場合も履歴に記録されるため、資金を元に戻せます。

エージェント経由で照合する前に知っておきたい制限が1つあります。YNABのAPIには、アカウントのlast_reconciled_atを設定するルートがありません。取引は実際に照合済みになりますが、アプリにはそこで最後に行った照合の日付が引き続き表示されます。ツールは、アカウントが照合済みだと報告する代わりに、この点を伝えます。

金額の単位

YNABの金額はすべてミリ単位です。1000 = $1.00

• 生のツールは、正規の金額フィールドにミリ単位の値を受け付け、返します。
• 拡張ツールは、正規の値とともに表示用の値を含むことがあります。

データについて

このサーバーがマシン上に保存するのは、history_revert で使用する、実行した書き込みの記録だけです。api.ynab.com 以外にデータが送信されることはなく、テレメトリーもありません。

uvx mcp-server-for-ynab history --show          # where it is, how much is there
uvx mcp-server-for-ynab history --export out.json
uvx mcp-server-for-ynab history --delete        # also removes the ability to revert

データを元に戻す場合も、削除する場合も、認証情報もエージェントも必要ありません。LLM を実行しなくてもできる必要があります。

コントリビューター向け

このリポジトリは、コントリビューターや AI エージェントが次の 3 つの疑問にすぐ答えられるように構成されています。MCP サーバーはどこにあるのか、YNAB API のラッパーとモデルはどこにあるのか、新しいツール、テスト、ドキュメントはどこに追加すればよいのか。

flowchart LR
    A["MCP Client"] --> B["MCPServer Server"]
    B --> C["Tool Handlers"]
    C --> D["ynab_client"]
    D --> E["http_client (httpx)"]
    E --> F["YNAB API"]
    C --> G["enriched/"]
    G --> D

コードは、次の少数のレイヤーを中心に構成されています。

• src/mcp_server_for_ynab/server/：MCPServer アプリ、ツールのメタデータ、ツールの登録、エラーバウンダリー
• src/mcp_server_for_ynab/ynab_client/：YNAB のリソースファミリーごとに 1 つの非同期ラッパーモジュール
• src/mcp_server_for_ynab/http_client/：リトライ、秘匿化、エラーの正規化に対応した、送信側の httpx ラッパー
• src/mcp_server_for_ynab/models/：型付きの YNAB データ構造、共有エラーモデル、ミリ単位のヘルパー
• src/mcp_server_for_ynab/enriched/：生のクライアントを基盤とする、より高水準の読み取り専用ワークフロー
• tests/：ユニットテスト、コントラクトテスト、統合テスト、QA／Postman のソースアセット

クローンから実行します。

git clone https://github.com/hs737/mcp-server-for-ynab
cd mcp-server-for-ynab
uv sync
cp .env.example .env    # then set YNAB_API_KEY

make smoke-stdio
make run-stdio
make run-http

テストを実行します。

make test
make test-unit
make test-contract
make test-integration
make test-postman-operator

これらのテストでは、サーバーが動作することを確認します。evals/ では別のことを確認します。つまり、アシスタントがサーバーを正しく使用するかです。このプロジェクトで実際に問題になったのは、1 回の呼び出しで済むはずのループによるレート制限でのロックアウトや、YNAB ではまだ古い状態のままなのに、アカウントを照合済みと報告するケースです。これらのケースはアサーションではなくモデルによって評価されるため、make check ではなく、必要に応じて claude plugin eval で実行します。evals/README.md を参照してください。

次に読むドキュメント

該当する項目を確認してください。

• クライアントを接続する場合：クライアントのセットアップ
• リポジトリの利用が初めての場合：アーキテクチャ
• コードを追加する場合：コントリビューション、リポジトリ構成、エージェント向けガイダンス
• ツールを追加または変更する場合：ツールの概要、エージェント評価
• 動作を検証する場合：テスト
• 認証、エラー処理、ログに取り組む場合：セキュリティ
• リリースを作成する場合、または配布チャネルを追加する場合：配布 — リリースノートはタグの注釈となるため、タグを付ける前に記述してください

全体については、ドキュメントインデックスを参照してください。こちらもご覧ください：Postman のメモ、 法的通知。

現在の状態

現在の実装では、Python 3.12、公式の mcp パッケージに含まれる MCPServer、全体を通じた asyncio、YNAB への外部呼び出し用の httpx、組み込みの stdio トランスポートとストリーム可能な HTTP トランスポートを使用しています。

これは、個人用アクセストークンを使うローカルサーバーです。ホスト型または公開コネクターは実装されていません。ローカルプロセスではなくリモートの HTTPS エンドポイントが必要な ChatGPT カスタムコネクターも対象に含まれます。ホスト型ランタイムは独自のリポジトリで運用し、このパッケージを埋め込み用インターフェイスを通じてインポートすることで、OAuth や公開アプリに関する懸念をこのプロジェクトの範囲外に保つことを意図しています。

アーキテクチャと実装が食い違った場合は、実際のコードを反映するよう更新されたアーキテクチャを正としてください。

ライセンス

Apache License 2.0 です。LICENSE と NOTICE.md をご覧ください。

免責事項

当プロジェクトは、YNAB またはその子会社・関連会社と提携、関係、または公式に結び付いているものではありません。YNAB の公式ウェブサイトは https://www.ynab.com です。

YNAB および You Need A Budget という名称ならびに関連する名称、商号、標章、商標、エンブレム、画像は、YNAB の登録商標です。