personal-finance-mcp-server

personal-finance-service용 원격 MCP 서버: 비즈니스 운영(그룹, 결제 수단, 지출)을 Keycloak으로 인증된 MCP 도구로 노출합니다. 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 참조 — 설계 결정, 알려진 격차, 그리고 인증 패스스루가 작동하는 이유(그리고 언제 작동이 중단되는지).