MCP YNAB Server 💰

MCP YNAB サーバー 💰

YNAB 用 MCP サーバー（TypeScript 版）へようこそ！🎉 このプロジェクトでは、Cursor（またはほかの MCP クライアント）を You Need A Budget（YNAB）アカウントに接続し、エディターから直接、財務データを操作できます。

1. これは何ですか？ 🤔（目的）

これは、公式 YNAB API への橋渡しをする、TypeScript による Model Context Protocol (MCP) の実装です。MCP 対応環境から YNAB データを読み書きするための標準化されたツールを提供し、Cursor のような AI アシスタントが財務管理を支援できるようにすることを目的としています。

2. 利用可能なツール 🛠️

このサーバーは、以下のツールを提供します。各ツールには詳細なドキュメントがあります。

• listBudgets：利用可能な予算の一覧を表示します。
• listAccounts：指定した予算内の口座の一覧を表示します。
• getAccountBalance：特定の口座の現在の残高を取得します。
• listCategories：指定した予算内のカテゴリーの一覧を表示します。
• getCategoryInfo：指定した月の特定のカテゴリーに関する詳細情報を取得します。
• getBudgetSummary：指定した月の予算概要（収入、予算計上額、アクティビティ）を表示します。
• listTransactions：予算の取引一覧を表示します。口座、カテゴリー、日付などで絞り込めます。
• createTransaction：予算に新しい取引または分割取引を作成します。

引数、出力、使用状況の詳細については、各ツールの README.md をご覧ください。

3. セットアップ 🚀

1. リポジトリをクローンします：

   # git clone https://github.com/Bulletninja/mcp-ynab # If you haven't already
   cd mcp-ynab 
   

2. 依存関係をインストールします：

   npm install
   

3. YNAB API トークンを設定します： YNAB の個人用アクセストークンが必要です。Cursor との連携で推奨され、テスト済みの方法は次のとおりです。

   • Cursor のグローバル設定ファイル ~/.cursor/mcp.json を編集します。
   • mcp-ynab のエントリーを追加または変更し、command、args、cwd、env が正しいことを確認します。

     {
       "mcpServers": {
         // ... other servers ...
         "mcp-ynab": {
           "command": "node",
           // 👇 コンパイル済みスクリプトへのパス
           "args": ["<path-to-your-project>/mcp-ynab/dist/server.js"], 
           "cwd": "<path-to-your-project>/mcp-ynab", // このプロジェクトへのパス
           "enabled": true,
           "env": {
             // 👇 正しい名前で YNAB トークンを設定します！
             "YNAB_API_TOKEN": "YOUR_YNAB_TOKEN_HERE" 
           }
         }
         // ... other servers ...
       }
     }
     

   • 代替方法（コードの変更が必要）： プロジェクトのルートに .env ファイルを置く方法もありますが、src/server.ts の dotenv の処理のコメントを解除し、サーバーモードに影響しないことを確認する必要があります。

4. コードをコンパイルします：

   npm run build
   

4. Cursor での使用 💡

1. ~/.cursor/mcp.json の設定が正しく、"enabled": true になっていることを確認します。
2. 更新した設定を読み込んでサーバーを起動するため、Cursor を再起動します。
3. これで完了です！Cursor の MCP 設定に、緑色の点と利用可能なツールの一覧とともに mcp-ynab が表示されます。
4. AI アシスタントにツールの使用を依頼できます。
   • 「YNAB の予算を一覧表示して」
   • 「budget_id 'last-used' で mcp_ynab_list_accounts を使って」
   • 「予算 Z にある口座 X（ID：YYY）の残高はいくらですか？」（mcp_ynab_get_account_balance が使われる場合があります）

5. 開発 🧑‍💻

• 開発モードでサーバーを実行（ホットリロードあり）： npm run dev
• テストを実行： npm test
• 本番環境／MCP 向けにコンパイル： npm run build
• CLI モード（コメントアウト済み）： node dist/server.js list-budgets のようなコマンドを実行するロジックは、Cursor の MCP サーバーモードと干渉するため、src/server.ts でコメントアウトされています。必要に応じてローカルテスト用にコメントを解除できますが、Cursor と連携する際は、必ず再度コメントアウトしてから再コンパイルしてください。