personal-finance-mcp-server

Remote MCP server for personal-finance-service: exposes its business operations (groups, payment methods, expenses) as MCP tools, authenticated with Keycloak. Intended to be used from Kiro/Claude (interactive login) or from a headless agent in the cloud (M2M login).

Requirements

• Docker + Docker Compose

• personal-finance-service running (docker compose up -d in that repo) — this server connects to its Keycloak and its API, it does not start them itself.

Related MCP server: Family Expense MCP

How to run it

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

MCP configuration in Kiro

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

On first use, Kiro opens the browser for the login against Keycloak — use the same username/password you already use in personal-finance-service.

Available tools

The management of personal-finance-service API Keys (create/list/delete) is deliberately not exposed as tools — see AGENTS.md.

Headless agent (M2M)

For an agent with no human user behind it (it cannot do the interactive login), use Client Credentials Grant instead of the Kiro flow:

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

Use that access_token as Bearer against POST /mcp. The agent also needs UPSTREAM_API_KEY configured in its environment — a Personal Finance API Key generated beforehand by a real user (POST /api-keys in personal-finance-service), since its token does not represent any real user of that API.

More detail

See AGENTS.md — design decisions, known gaps, and why the auth passthrough works (and when it would stop working).