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）

对于没有人类用户背后的代理（无法进行交互式登录），请使用客户端凭据授权（Client Credentials Grant）而不是 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

使用该 access_token 作为 Bearer 令牌调用 POST /mcp。代理还需要 在其环境中配置 UPSTREAM_API_KEY——一个由真实用户预先生成的 Personal Finance API 密钥（在 personal-finance-service 中执行 POST /api-keys）， 因为其令牌不代表该 API 的任何真实用户。

更多详情

参见 AGENTS.md——设计决策、已知差距，以及为什么认证透传 有效（以及何时会失效）。