personal-finance-mcp-server

MCP server remoto para personal-finance-service: expone sus operaciones de negocio (grupos, medios de pago, gastos) como tools MCP, autenticado con Keycloak. Pensado para usarse desde Kiro/Claude (login interactivo) o desde un agente headless en la nube (login M2M).

Requisitos

• Docker + Docker Compose

• personal-finance-service corriendo (docker compose up -d en ese repo) — este server se conecta a su Keycloak y su API, no los levanta él mismo.

Related MCP server: MCP Agent - AI Expense Tracker

Cómo correrlo

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 — requiere Authorization: Bearer <jwt>

Configuración del MCP en Kiro

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

Al primer uso, Kiro abre el browser para el login contra Keycloak — usa el mismo usuario/contraseña que ya usás en personal-finance-service.

Tools disponibles

La gestión de API Keys de personal-finance-service (crear/listar/borrar) deliberadamente no está expuesta como tools — ver AGENTS.md.

Agente headless (M2M)

Para un agente sin usuario humano detrás (no puede hacer el login interactivo), usá Client Credentials Grant en vez del flujo de Kiro:

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

Usá ese access_token como Bearer contra POST /mcp. El agente además necesita UPSTREAM_API_KEY configurada en su entorno — una Personal Finance API Key generada de antemano por un usuario real (POST /api-keys en personal-finance-service), ya que su token no representa a ningún usuario real de esa API.

Más detalle

Ver AGENTS.md — decisiones de diseño, gaps conocidos, y por qué el passthrough de auth funciona (y cuándo dejaría de funcionar).