personal-finance-mcp-server

Удалённый MCP-сервер для personal-finance-service: он предоставляет его бизнес-операции (группы, способы оплаты, расходы) как инструменты MCP, с аутентификацией через Keycloak. Предназначен для использования из Kiro/Claude (интерактивный вход) или из headless-агента в облаке (вход 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>

Настройка MCP в Kiro

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

При первом использовании Kiro открывает браузер для входа через Keycloak — используйте те же имя пользователя и пароль, что вы уже используете в personal-finance-service.

Доступные инструменты

Управление API-ключами personal-finance-service (создание/просмотр/удаление) намеренно не представлено как инструменты — см. AGENTS.md.

Headless-агент (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 Key, заранее созданный реальным пользователем (POST /api-keys в personal-finance-service), поскольку его токен не представляет ни одного реального пользователя этого API.

Подробнее

См. AGENTS.md — проектные решения, известные пробелы и почему проброс аутентификации работает (и когда он перестанет работать).