personal-finance-mcp-server

personal-finance-service 用のリモートMCPサーバー: ビジネスオペレーション(グループ、支払い方法、支出)をMCPツールとして公開し、Keycloakで認証します。Kiro/Claude(インタラクティブログイン)またはクラウド上のヘッドレスエージェント(M2Mログイン)から使用することを想定しています。

要件

• Docker + Docker Compose

• personal-finance-service が実行中であること(そのリポジトリで docker compose up -d) — このサーバーはそのKeycloakとAPIに接続しますが、それらを起動するわけではありません。

Related MCP server: MCP Agent - AI Expense Tracker

実行方法

cp .env.example .env
# completar KEYCLOAK_CLIENT_SECRET con el secret de mcp-personal-finance-server
# (ver "Setup de Keycloak" en AGENTS.md si todavía no existen los clients)
docker compose up -d --build

• GET http://localhost:8000/health

• POST http://localhost:8000/mcp — Authorization: Bearer <jwt> が必要

KiroでのMCP設定

{
  "mcpServers": {
    "personal-finance-remote": {
      "url": "http://localhost:8000/mcp",
      "oauth": {
        "clientId": "mcp-personal-finance-client",
        "scopes": []
      }
    }
  }
}

初回使用時、KiroはKeycloakへのログイン用にブラウザを開きます — personal-finance-service で既に使用しているユーザー名/パスワードを使用してください。

利用可能なツール

personal-finance-service のAPIキー管理(作成/一覧/削除)は、意図的にツールとして公開されていません — AGENTS.md を参照してください。

ヘッドレスエージェント(M2M)

背後に人間のユーザーがいないエージェント(インタラクティブログインができない)の場合、KiroのフローではなくClient Credentials Grantを使用してください:

curl -X POST http://localhost:8080/realms/personal-finance/protocol/openid-connect/token \
  -d "grant_type=client_credentials&client_id=mcp-personal-finance-agent&client_secret=$AGENT_CLIENT_SECRET" \
  | jq -r .access_token

その access_token を POST /mcp に対するBearerとして使用してください。エージェントはさらに、環境に UPSTREAM_API_KEY を設定する必要があります — 実際のユーザーがあらかじめ生成したPersonal Finance API Key(personal-finance-service の POST /api-keys)です。なぜなら、そのトークンはそのAPIの実際のユーザーを表していないからです。

詳細

AGENTS.md を参照 — 設計上の決定、既知のギャップ、そして認証パススルーが機能する理由(そしていつ機能しなくなるか)。