ynab-mcp

YNAB（You Need A Budget）の家計データをRead-onlyで読み取る個人用MCPサーバー。Claude Desktop / Claude CodeからDaily/Weekly/Monthlyの支出振り返り・計画支援に使う。

書き込み機能は一切なし。詳細な要件・設計は docs/requirements.ja.md / docs/design.ja.md を参照（日本語版が正）。

セットアップ

uv sync

YNABのPersonal Access Token（YNAB設定画面で発行）をシェルの環境変数にexportする。リポジトリには一切書き込まない。

# ~/.zshrc 等に追記
export YNAB_API_TOKEN="your-personal-access-token"

任意の追加設定（省略可）:

環境変数	用途	既定値
YNAB_DEFAULT_BUDGET_ID	Budgetが複数ある場合の既定budget_id	なし(単一Budgetなら自動解決)
YNAB_MCP_CACHE_TTL	プロセス内キャッシュのTTL(秒)	300
YNAB_MCP_WEEK_START	週の開始曜日(0=月曜)	0

動作確認

uv run ruff check .
uv run pytest
uv run python -c "from ynab_mcp.server import mcp"   # importスモークテスト

Claude Codeへの登録

このリポジトリの .mcp.json にプロジェクトスコープで登録済み。ynab_mcp ディレクトリで作業する際、Claude Codeが自動的にサーバーを認識する（初回は承認プロンプトが出る）。

Claude Desktopへの登録

Claude Desktopの設定ファイル（~/Library/Application Support/Claude/claude_desktop_config.json）の mcpServers に以下を追加する。

{
  "mcpServers": {
    "ynab": {
      "command": "uv",
      "args": ["run", "--directory", "/path/to/ynab_mcp", "ynab-mcp"],
      "env": { "YNAB_API_TOKEN": "${YNAB_API_TOKEN}" }
    }
  }
}

提供するTool

• list_budgets — Budget一覧
• get_categories(budget_id?) — カテゴリと当月のbudgeted/activity/balance
• list_transactions(budget_id?, since_date?, until_date?, category_id?, type?) — 取引明細
• get_period_summary(period, budget_id?, date?) — 期間別の支出実績+月次予算からの按分ペース(参考値)

提供するPrompt

• daily_review / weekly_review / monthly_review — 定型の振り返りプロンプト

License

Apache License 2.0. 詳細は LICENSE を参照。