# ynab-mcp

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

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

## セットアップ

```bash
uv sync
```

YNABのPersonal Access Token（[YNAB設定画面](https://app.ynab.com/settings/developer)で発行）をシェルの環境変数にexportする。リポジトリには一切書き込まない。

```bash
# ~/.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 |

## 動作確認

```bash
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` に以下を追加する。

```json
{
  "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](./LICENSE) を参照。