ynab-mcpb

デモ

_{レシートを貼り付ける → 数秒で明細ごとに分割された取引が完成}

できること

仕組み

graph LR
    U(You) -->|Plain English| C[Claude Desktop<br/>or any MCP client]
    C -->|MCP protocol| S[YNAB MCP Server<br/>35 tools]
    S -->|YNAB API| Y[(Your Budget)]

    style S fill:#2563EB,color:#fff,stroke:#1d4ed8
    style Y fill:#16a34a,color:#fff,stroke:#15803d
    style C fill:#7c3aed,color:#fff,stroke:#6d28d9

特長

• レシートの明細化 — レシートを貼り付けると、明細項目ごとに税額が自動配分された分割取引を作成できます。
• 銀行口座の照合（ベータ版） — 銀行の CSV をインポートし、YNAB の取引とあいまい一致で照合して、不足または不一致の取引を検出し、一括修正できます。
• 35 個の YNAB ツール — 予定取引と決定論的な期間分析を含む、幅広い機能を利用できます。
• 書き込みはデフォルトで安全 — プレビューモードでは、検証済みのリクエストそのものにひも付けられた、短時間のみ有効な一度限りの確認が必要です。
• 小規模なツールプロファイル — 起動時に core、read-only、full を選択できます。動的な登録は行いません。
• 差分同期 — 前回のリクエスト以降に変更されたデータのみを取得するため、高速に動作します。
• Markdown または JSON — すべての読み取りツールで response_format を利用でき、人間が読みやすい Markdown テーブル（デフォルト）または構造化 JSON を選択できます。
• MCP ネイティブ — 構造化出力、アノテーション、補完 API、リソーステンプレートに対応しています。

照合の仕組み

sequenceDiagram
    participant You
    participant Claude
    participant MCP as YNAB MCP Server
    participant YNAB

    You->>Claude: "Reconcile my checking<br/>with this CSV"
    Claude->>MCP: reconcile_account(csv_data)
    MCP->>YNAB: Fetch transactions
    YNAB-->>MCP: YNAB transactions
    MCP->>MCP: Parse CSV<br/>Fuzzy-match payees & dates<br/>Detect missing / mismatched
    MCP-->>Claude: Matches + recommendations
    Claude->>You: "Found 47 matches, 3 missing.<br/>Apply changes?"
    You->>Claude: "Yes"
    Claude->>MCP: Apply recommended changes
    MCP->>YNAB: Create / update transactions
    MCP-->>Claude: Done
    Claude->>You: "3 transactions created,<br/>account reconciled."

セットアップ（2 分）

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

1. YNAB Web アプリを開きます
2. アカウント設定 → 開発者設定 → 新しいトークンに移動します
3. トークンをコピーします（表示されるのは一度だけです）

2 — インストールする

{
  "mcpServers": {
    "ynab": {
      "command": "npx",
      "args": ["-y", "@dizzlkheinz/ynab-mcpb@latest"],
      "env": {
        "YNAB_ACCESS_TOKEN": "your-token-here"
      }
    }
  }
}

{
  "mcpServers": {
    "ynab": {
      "command": "npx",
      "args": ["-y", "@dizzlkheinz/ynab-mcpb@latest"],
      "env": {
        "YNAB_ACCESS_TOKEN": "your-token-here"
      }
    }
  }
}

[mcp_servers.ynab-mcpb]
command = "npx"
args = ["-y", "@dizzlkheinz/ynab-mcpb@latest"]
env = {"YNAB_ACCESS_TOKEN" = "your-token-here"}
startup_timeout_sec = 120

3 — 次のプロンプトを試す

List my budgets and set the default to my main budget.
Show recent transactions in my checking account.
How much did I spend on groceries in the last 30 days?
Create a transaction: $42.18 at Trader Joe's yesterday.

ツール（35）

設定

すべてのオプションについては .env.example を参照してください。

書き込みモードと互換性

preview は保守的な既定値です。変更操作の呼び出しでは、まず既存の dry_run 処理を実行し、確認トークンを返します。このトークンは 2 分後に期限切れとなり、一度だけ使用でき、同じ正規ツール名と検証済み引数に対してのみ有効です。read-only では、YNAB の変更操作ツールは登録されません。enabled は、明示的にオプトインしたユーザー向けに、安全対策導入前の直接書き込み動作を維持します。

取引金額には、amount_decimal（例：-12.34）または明示的な生データフィールド amount_milliunits（-12340）が優先して使用されるようになりました。カテゴリへの割り当て額には、budgeted_decimal または budgeted_milliunits が優先して使用されます。旧来の amount と budgeted フィールドも、後方互換性のため、非推奨のミリ単位エイリアスとして引き続き受け付けられます。これらの意味を推測することはありません。

ツールプロファイル

プロファイルはサーバー起動時に一度だけ選択されるため、クライアントが受け取る tools/list の応答は安定しています。

• core には、一般的な読み取り、取引の安全なワークフロー、照合、レシートの分割、定期取引の確認、支出分析が含まれます。
• read-only では、読み取り専用と明示的に注釈されたすべてのツールを公開します。
• full では、選択した書き込みモードに従い、35 個のツールすべてを公開します。

プライバシーと信頼

• サーバープロセスはローカルで実行され、YNAB の API を介して YNAB と通信します。
• YNAB の個人用アクセストークンは機密情報です。MCP クライアントのシークレット設定に保存し、会話、issue、フィクスチャ、ログには決して貼り付けないでください。
• ツールが返し、会話に含まれる財務データは、MCP クライアントで選択した AI プロバイダーによって処理される場合があります。機密情報を共有する前に、そのプロバイダーのデータ管理設定を確認してください。
• トランザクションのエクスポートファイルはローカルディスクの YNAB_EXPORT_PATH（またはプラットフォームのデフォルトの場所）に保存されます。サーバーがエクスポートファイルを他の場所へアップロードすることはありません。
• YNAB への書き込みを行わない場合は read-only、リクエストの内容を正確に確認する場合は preview、直接書き込むことが意図的な互換性上の選択である場合にのみ enabled を使用してください。
• この独立したオープンソースプロジェクトは、YNAB とは提携しておらず、YNAB の推奨を受けているものでもありません。

トラブルシューティング

開発者向け

git clone https://github.com/dizzlkheinz/ynab-mcpb.git
cd ynab-mcpb
npm ci --ignore-scripts
npm run build
npm test
npm run test:integration

ビルドとオフラインテストに YNAB の認証情報は必要ありません。npm test はユニットテストとパフォーマンステストを実行します。test:integration はモックを使用した統合テストを実行します。テスト一式、カバレッジ、ウォッチモードには、それぞれ test:all、test:coverage、test:watch を使用してください。たとえば npm run test:integration -- transactionTools のように、ファイル名やテスト名のフィルターを直接渡せます。

サーバーをローカルで起動するには、.env.example を .env にコピーし、トークンを追加してから npm start を実行してください。実環境でのスモークテストには、明示的に RUN_LIVE_YNAB_TESTS=true を設定する必要があります。テストは npm run test:live で実行します。SKIP_E2E_TESTS=true を設定すると、テストは無効になります。

ビルドでは、グローバルツールのパッケージ化やインストールは行われません。Claude Desktop バンドルを作成するには、公式 CLI を一度インストールしてから（npm install --global @anthropic-ai/mcpb）、npm run build と npm run package:mcpb を実行してください。npm pack --dry-run --ignore-scripts で npm パッケージの内容を確認してください。

アーキテクチャとコントリビューター向けガイダンス：CLAUDE.md

照合アーキテクチャ：docs/technical/reconciliation-system-architecture.md

コントリビューション

バグ報告や、CSV のエッジケースを再現できる事例を歓迎します。特に銀行口座の照合に関する報告をお待ちしています。 issue を作成

PR も歓迎します。提出前に npm test と npm run lint を実行してください。

ライセンス

AGPL-3.0