personal-finance-mcp-server

MCP-Server für personal-finance-service: stellt seine Geschäftsoperationen (Gruppen, Zahlungsmittel, Ausgaben) als MCP-Tools bereit, authentifiziert mit Keycloak. Gedacht für die Verwendung von Kiro/Claude (interaktiver Login) oder von einem headless Agenten in der Cloud (M2M-Login).

Voraussetzungen

• Docker + Docker Compose

• personal-finance-service läuft (docker compose up -d in diesem Repo) – dieser Server verbindet sich mit dessen Keycloak und API, er startet sie nicht selbst.

Related MCP server: MCP Agent - AI Expense Tracker

So führen Sie es aus

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 – erfordert Authorization: Bearer <jwt>

MCP-Konfiguration in Kiro

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

Beim ersten Gebrauch öffnet Kiro den Browser für den Login gegen Keycloak – verwenden Sie denselben Benutzernamen und dasselbe Passwort, das Sie bereits in personal-finance-service verwenden.

Verfügbare Tools

Die Verwaltung der API-Keys von personal-finance-service (erstellen/auflisten/löschen) ist bewusst nicht als Tools exponiert – siehe AGENTS.md.

Headless-Agent (M2M)

Für einen Agenten ohne menschlichen Benutzer dahinter (der den interaktiven Login nicht durchführen kann), verwenden Sie den Client-Credentials-Grant anstelle des Kiro-Flows:

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

Verwenden Sie dieses access_token als Bearer gegen POST /mcp. Der Agent benötigt außerdem UPSTREAM_API_KEY, die in seiner Umgebung konfiguriert ist – eine Personal Finance API Key, die zuvor von einem echten Benutzer generiert wurde (POST /api-keys in personal-finance-service), da sein Token keinen echten Benutzer dieser API repräsentiert.

Weitere Details

Siehe AGENTS.md – Designentscheidungen, bekannte Lücken und warum der Auth-Passthrough funktioniert (und wann er aufhören würde zu funktionieren).