mcp-for-ynab

MCP for YNAB

YNAB 向けの高速で安全な MCP サーバーです。Claude やその他の AI アシスタントから予算にフルアクセスできます。デフォルトでは読み取り専用です。

予算、取引、カテゴリ、受取人、口座、予定されている取引、およびサーバー側で計算する分析（支出の概要、予算の健全性、定期的な請求、収入と支出、純資産、月締めのカバレッジ、カテゴリとクレジットカードのフロート履歴）を扱う35個のツールを備えています。書き込みは明示的に有効にしない限り無効です。リスクのある書き込みには確認が必要で、既存データを編集または削除する書き込みは元に戻せます。

インストール

Cove for YNAB の実行方法は2つあります。ローカル（npm パッケージ。1度に1つのクライアントで使用）と、リモート（URLとトークンを1つずつ指定。Desktop、Code、モバイルで同じように動作）です。

インストール（ローカル）

npx を使ってマシン上で実行します。Claude Code と Claude Desktop で動作します。モバイルからは接続できません。モバイルクライアントでは、以下のリモート方式が必要です。

Claude Code:

claude mcp add ynab -e YNAB_ACCESS_TOKEN=xxx -- npx -y @walensis/cove-mcp

Claude Desktop — 以下を設定ファイル（claude_desktop_config.json）に追加します。

{
  "mcpServers": {
    "cove": {
      "command": "npx",
      "args": ["-y", "@walensis/cove-mcp"],
      "env": {
        "YNAB_ACCESS_TOKEN": "xxx"
      }
    }
  }
}

xxx を個人用アクセストークンに置き換えてください（下記のトークンの取得を参照）。デフォルトではサーバーは読み取り専用です。書き込みツールを使う場合は、env に "YNAB_ALLOW_WRITES": "1" を追加するか、Claude Code の -e で環境変数を設定してください。デフォルトでは読み取り専用（書き込みはオプトイン）を参照してください。

stdio 経由で MCP を利用するその他のクライアントでも、同じ方法でサーバーを実行できます。

npx -y @walensis/cove-mcp

その際、環境変数に YNAB_ACCESS_TOKEN を設定してください。

インストール（リモート）

URLとトークンを1つずつ設定すれば、Claude Desktop、Claude Code、モバイルの claude.ai で同じように動作します。ローカルプロセスを起動し続ける必要はありません。これは apps/worker で、自分のアカウントにデプロイする、シングルテナントの Cloudflare Worker です。YNAB トークンも自分のものを使用します。完全なデプロイ手順と、各種クライアントの接続方法については、apps/worker/README.mdを参照してください。

モデルの概要： このリポジトリに含まれるエンジン、stdio サーバー、リモートエンドポイントはすべてオープンソースかつ無料で、ツールとして動作します。ステートレスで、要求に応じて応答し、自ら動作することはありません。常時稼働するフロート監視、ダイジェスト、LLM が作成する説明、ブラウザー拡張機能など、自律的に動作する機能や従量課金の機能はプロダクトであり、別のホスティングサービスとして提供し、料金をいただきます。この Worker をセルフホストすれば、ツール部分を永久に無料で利用できますが、常時稼働する機能は含まれません。同じオープンエンジンを基盤に、それらの機能を自分で構築する場合は、docs/build-your-own-monitoring.mdを参照してください。

トークンの取得

1. app.ynab.comにアクセスしてサインインします。
2. Account Settings → Developer Settings を開きます。
3. Personal Access Tokens の下にある New Token をクリックし、パスワードを確認して、トークンをコピーします。
4. その値を YNAB_ACCESS_TOKEN として使用します。パスワードと同様に扱ってください。このトークンを持つ人は、トークンが有効な間、予算にフルアクセスできます。

トークンを MCP クライアントの設定に直接記載したくない場合は、トークンだけが記載されたファイルのパスを YNAB_ACCESS_TOKEN_FILE に設定してください。

デフォルトでは読み取り専用、書き込みはオプトイン

デフォルトでは、このサーバーは読み取りツールのみを公開します。予算を変更する操作は一切行いません。書き込みツール（取引の作成・編集・削除、金額の割り当てなど）を有効にするには、次の値を設定します。

YNAB_ALLOW_WRITES=1

サーバーの環境変数に設定して、再起動してください。書き込みを有効にすると、次のようになります。

• 確認ゲート：破壊的な操作や一括操作（取引の削除、予定取引の削除、5件を超える取引の一括更新）には、明示的な confirm: true が必要です。また、一括更新では expected_count も行数と一致させる必要があります。そのため、アシスタントは操作を実行する前に、何を実行するかを提示する必要があります。
• 元に戻す：既存データを変更する書き込み（取引の編集・削除、カテゴリの編集、予算の割り当て・移動、予定取引の編集・削除、受取人名の変更）はローカルに記録され、undo_last ツールで直近の変更を取り消せます（最大50件の書き込み履歴が ~/.cove/undo.json に保存されます）。何かを作成する書き込み（create_category、create_payee、create_account）と import_transactions は取り消せません。YNAB の API にはカテゴリ、受取人、口座を削除する機能がなく、インポートを元に戻す方法もありません。これらも引き続き記録されるため、取り消し履歴の順序は維持されますが、undo_last は該当する項目を取り消せないことを伝え、その前の書き込みに進みます。詳しくは、このファイルについて記載された PRIVACY.md を参照してください。

レート制限

基盤となる API では、同じトークンを使うすべてのアプリ（このサーバー、YNAB のモバイルアプリやウェブアプリ、その他の連携など）で共有される、トークンあたり毎時200リクエストの制限があります。このサーバーはクライアント側で自身の使用量を追跡し、他のアプリのための余裕を残すため、毎時190リクエストで動作を停止します。また、可能な場合は生の行データを大量に出力するのではなく、小さなサーバー計算済みの応答（集計、要約）を優先します。

ツール

ツール	種別	説明
list_plans	読み取り	すべての予算（プラン）を一覧表示します：ID、名前、通貨、最終更新日時。
get_plan_overview	読み取り	1 回の呼び出しで全体像を把握します：口座、当月の「Ready to Assign」、お金の経過期間、カテゴリ別合計。
get_month	読み取り	指定した 1 か月の詳細情報：「Ready to Assign」、お金の経過期間、すべてのカテゴリのステータス。
list_transactions	読み取り	フィルター、ページネーション、フィールド選択を使って取引を一覧表示または集計します。
get_transaction	読み取り	分割されたサブ取引を含む、1 件の取引の詳細情報。
create_transactions	書き込み	分割とインポート時の重複排除に対応し、1 件以上の取引を一括作成します。
update_transactions	書き込み	取引を一括編集します：カテゴリ設定、承認、決済済み設定、フィールド編集。
delete_transaction	書き込み	1 件の取引を削除します。確認が必要です。
import_transactions	書き込み	リンク済み口座の取引のインポートを開始します。
list_scheduled_transactions	読み取り	すべての予定済み（今後の予定／定期）取引。
create_scheduled_transaction	書き込み	予定済み取引（今後の請求または定期収入）を作成します。
update_scheduled_transaction	書き込み	予定済み取引を更新します。
delete_scheduled_transaction	書き込み	予定済み取引を削除します。確認が必要です。
list_categories	読み取り	残高と目標ステータスを含む、表示可能なすべてのカテゴリ。
create_category	書き込み	カテゴリを作成します（必要に応じてグループも作成します）。
update_category	書き込み	カテゴリ名の変更、非表示化、または目標の設定を行います。
assign_budget	書き込み	指定した月のカテゴリの割り当て額を設定します。
move_money	書き込み	指定した月に、2 つのカテゴリ間で割り当て済み資金をアトミックに移動します。
list_payees	読み取り	すべての支払先（ID、名前、振替フラグ）。
rename_payee	書き込み	支払先に関連するすべての取引で、支払先名を変更します。
create_payee	書き込み	支払先を作成します。
create_account	書き込み	開始残高を指定して口座を作成します。
spending_summary	読み取り	カテゴリ別または支払先別の、サーバーが計算した支出額。期間比較も指定できます。
budget_health	読み取り	当月の健全性チェック：過剰支出、目標への資金不足、クレジットカードのフロート。
detect_recurring_charges	読み取り	約 13 か月分の履歴から、定期的な請求（サブスクリプション／請求）を検出します。
income_vs_expense	読み取り	月ごとの収入／支出／純額の系列。
net_worth_history	読み取り	すべての取引履歴から計算した、月ごとの純資産の系列。
month_close	読み取り	指定した締め日を対象とした月締めレポート：クレジットカードの充当状況、阻害要因、過剰支出のカテゴリ、優先順位付きの資金提供元。
propose_coverage	読み取り	指定した締め月に、過剰支出のあるすべてのカテゴリをゼロにするための、優先順位付き資金移動案。
get_category_history	読み取り	指定した月範囲における、1 つのカテゴリの月次系列（割り当て額／利用額／利用可能額）。
credit_card_float_history	読み取り	指定した範囲における月ごとのクレジットカードのフロート分析：債務額と支払いカテゴリの利用可能額、差額、変更フラグ。
backfill_ledger	ローカル書き込み	履歴からローカルの残高繰越台帳を補完します。完全に経過した月ごとにカード 1 枚あたり 1 件の記録を作成し、原因と検出サマリー（「 から $X を繰り越し」）を含みます。ローカルファイルのみ（~/.cove/ledger.json）に書き込み、YNAB には一切変更を加えません。
record_month_close	ローカル書き込み	月締めの残高繰越記録（カードごとの差額、阻害要因、原因、適用した資金移動）を保存します。ローカルファイルのみ（~/.cove/ledger.json）に書き込み、YNAB には一切変更を加えません。
get_month_close_ledger	読み取り	過去の残高繰越記録を読み込みます（新しい順）。締め日で絞り込むこともできます。
undo_last	書き込み	このサーバーを通じて行われた直近の書き込みを取り消します。

月次締めセッション

上記のツールを基盤とする、月次の状況確認をガイドするフロー（残高 → 計画）です。カバーできていない項目を解消し、カバー不足額を信頼できる状態にするまで進めます。クレジットカードのフロートの変動原因を特定し、寄付者を優先したカバーの移動を提案します。そして、承認を受けると、record_month_close を使って残高繰越レコードを書き込み、翌月のセッションが比較に使える基準値を用意します（get_month_close_ledger）。初回実行時は台帳が空のため、セッションはまず各カードについて backfill_ledger を実行し、見つかった内容（例：「2024-08 から 865.75 ドルを繰り越しています」）を提示してから、それ以外の原因を特定します。

• Claude Code：/month-close スキルを使います。
• Claude Desktop およびその他の MCP クライアント：サーバーは同じフローを month-close-session MCP プロンプトとして公開します。
• 手順の詳細：docs/playbooks/month-close.md。

リモート MCP エンドポイント（セルフホスト）

リモートワーカー（上記のインストール（リモート）を参照）は、トークン認証されたリモート MCP エンドポイントを通じて、同じ 35 個のツールを公開します。ヘッダーに対応したクライアント向けのベアラーヘッダールートに加え、claude.ai の URL のみを使うカスタムコネクターから予算に直接アクセスできるよう、トークンをパスに含めるルートも用意しています。これは、このパッケージが埋め込み用にエクスポートするのと同じライブラリエントリーポイントを基盤としています。

import { tools, buildServer } from '@walensis/cove-mcp'

常時稼働のモニタリングは含まれていません。これは別途提供されるホスト型製品です。同じオープンなアトリビューションエンジンを使って独自に構築する場合は、docs/build-your-own-monitoring.mdを参照してください。

デプロイ手順の全容：apps/worker/README.md。

開発

これは pnpm モノレポです。packages/core（@walensis/cove-core。YNAB 用 API クライアントおよびドメインロジック）と、apps/mcp（@walensis/cove-mcp。それをラップする MCP サーバー）で構成されています。

名称： Cove は製品名です。@walensis/cove-core はエンジン、@walensis/cove-mcp は MCP のインターフェースです。また、MCP レジストリーのエントリーでは、見つけやすさを考慮して、説明的な mcp-for-ynab という名前を維持しています。

pnpm install
pnpm build
pnpm test
pnpm typecheck

実際の予算を使ってスモークテストするには（読み取り専用のため、書き込みは行いません）：

YNAB_ACCESS_TOKEN=xxx pnpm smoke

既知の正常なフィクスチャ値を使って credit_card_float_history を検証するには（読み取り専用）：

YNAB_ACCESS_TOKEN=xxx pnpm validate:fixtures

免責事項

当社は YNAB およびその子会社や関連会社と、提携、関連、またはその他の公式な関係を一切有していません。

ライセンス

MIT © walensis-labs