YNAB MCP

YNAB MCP

You Need A Budget（YNAB）と連携する Claude Code 向けの YNAB Model Context Protocol（MCP）サーバーです。

概要

このリポジトリには、Claude Code が YNAB（You Need A Budget）のアカウントとやり取りできる、Docker ベースの MCP サーバーが含まれています。OAuth フローを実装し、予算管理、取引の追跡、財務分析のための包括的な API を提供します。

既知の問題

MCP ツールの利用可能性

以下の問題が確認されています。

1. 取引 API — sinceDate パラメーターを使用すると、list_transactions エンドポイントで「invalid date」エラーが発生します
2. API ツールの不足 — ソースコードで定義されている複数のエンドポイントを、MCP 統合で利用できません
3. 動作の不整合 — test-mcp.js を使ったテストでは動作するツールの一部が、実際の MCP 統合では失敗します

問題の追跡

以下の修正に取り組んでいます。

• fix-transactions-api ブランチ：取引 API の日付形式の処理を修正します
• fix-mcp-registration ブランチ：すべての API ツールが適切に登録され、利用できるようにします

機能

• YNAB API による OAuth ベースの認証
• 予算とアカウントの包括的な管理
• 取引の作成とカテゴリ分け
• 一括割り当てや推奨機能を備えた高度なカテゴリ管理
• 複数の予算（個人用および家族用）に対応
• レート制限への対応（YNAB API の上限：1 時間あたり 200 リクエスト）
• パフォーマンス向上のためのキャッシュ

新しいカテゴリ管理機能

この MCP には、以下の高度なカテゴリ管理機能が含まれています。

• カテゴリへの割り当て：Ready to Assign から複数のカテゴリへ、一度の操作で資金を割り当てます
• 推奨割り当て：目標や支出傾向に基づいて、AI を活用した予算配分の提案を取得します

詳細はカテゴリ管理のドキュメントをご覧ください。

はじめに

前提条件

• Docker
• Node.js v18+（開発用）
• Claude Code CLI
• YNAB アカウント

インストール

1. このリポジトリをクローンします
2. config/config.example.js を config/config.js にコピーし、YNAB API の認証情報を追加します
3. Docker イメージをビルドします：docker build -t ynab-mcp:latest .
4. Claude 用の JSON 設定を作成します：

   {
     "command": "docker",
     "args": [
       "run",
       "--rm",
       "-i",
       "-v",
       "/path/to/data:/app/data",
       "-v",
       "/path/to/config:/app/config",
       "-e",
       "NODE_ENV=production",
       "ynab-mcp:latest"
     ]
   }
   

5. Claude Code CLI に MCP を登録します：

   claude mcp add-json ynab '{"command": "docker", "args": ["run", "--rm", "-i", "-v", "/path/to/data:/app/data", "-v", "/path/to/config:/app/config", "-e", "NODE_ENV=production", "ynab-mcp:latest"]}'
   

   JSON をファイルに保存して、次のコマンドを使用することもできます：

   claude mcp add-json ynab "$(cat config.json)"
   

6. Claude から求められたら、YNAB アカウントで認証します

Claude との統合

この MCP は Claude とシームレスに統合され、以下が可能になります。

• 予算と取引の表示
• 財務分析の取得
• 自然な会話を通じた予算管理

セキュリティ

• トークンはマウントされた Docker ボリュームに安全に保存されます
• 機密データはログに記録されません
• 認証には OAuth 2.0 標準を使用します
• 読み取り専用モードに対応しています

実装の詳細

この実装は、以下を使用して Model Context Protocol 標準に準拠しています。

• Node.js と公式 MCP SDK
• コンテナ化とデプロイのための Docker
• API 操作のための YNAB JavaScript SDK
• 認証のための OAuth 2.0

ライセンス

MIT

謝辞

• YNAB API
• YNAB JavaScript Library
• Anthropic Claude