mcp-keycloak

Keycloak용 Model Context Protocol 서버입니다. MCP를 지원하는 클라이언트(Claude Desktop, Claude Code 등)가 Keycloak의 realm, 사용자, 클라이언트, 역할, 그룹을 조회하고 관리할 수 있게 하며, 보안은 전적으로 플래그에 의해 제어됩니다.

설계 목표는 안전이 기본값이라는 것입니다. 읽기 전용으로 시작하고, Realm 허용 목록으로 범위를 제한하며, 민감한 Realm은 변경으로부터 보호하고, 파괴적인 작업은 명시적인 옵트인을 거쳐야만 허용됩니다.

기능

• 멀티 Realm — 모든 도구는 realm 인자를 받습니다. 허용 목록으로 범위를 제한할 수 있습니다.

• 접근 모드 — read-only → read-write → admin 순서로 계층화되어, 각 모드는 현재 수준보다 높은 도구를 절대 노출하지 않습니다.

• 보안 플래그 — Realm 허용 목록, 보호되는 Realm, 삭제 통제, dry-run, JSON 감사 로깅(아래 참조)

• 두 가지 인증 방식 — 기밀 클라이언트 서비스 계정(권장) 또는 관리자 사용자 이름/비밀번호.

• 무거운 의존성 없음 — 가벼운 fetch 기반 Admin REST 클라이언트와 MCP SDK 및 zod만 사용합니다.

Related MCP server: mcp-keycloak-admin

보안 모델

이 계층들은 서로 독립적입니다. 예를 들어 KEYCLOAK_ALLOW_DELETE=false인 admin 모드는 사용자를 생성하고 업데이트할 수 있지만 삭제할 수는 없습니다.

도구

읽기 (read-only+): list_realms, get_realm, list_users, get_user, count_users, list_clients, list_realm_roles, list_groups

쓰기 (read-write+): create_user, update_user, reset_password, logout_user

관리자 (admin): delete_user

MCP 클라이언트와 함께 사용하기

Claude Code, Claude Desktop, Cursor, OpenAI Codex CLI, Windsurf, VS Code(Copilot) 등 모든 MCP 클라이언트에서 동작합니다. 클라이언트별 설정은 docs/CLIENTS.md 를 참조하세요.

설치

npm install
npm run build

설정

.env.example을 복사하고 값을 채우거나, MCP 클라이언트 설정에 변수를 직접 넣으세요. 필요한 realm-management 역할을 가진 기밀 클라이언트가 권장되는 자격 증명입니다.

Claude Desktop / Claude Code에서 실행하기

claude_desktop_config.json 또는 claude mcp add 명령으로 MCP 클라이언트 설정에 추가하세요:

{
  "mcpServers": {
    "keycloak": {
      "command": "node",
      "args": ["/absolute/path/to/mcp-keycloak/dist/index.js"],
      "env": {
        "KEYCLOAK_URL": "https://keycloak.example.com",
        "KEYCLOAK_CLIENT_ID": "admin-cli",
        "KEYCLOAK_CLIENT_SECRET": "your-secret",
        "KEYCLOAK_MODE": "read-only",
        "KEYCLOAK_REALM_ALLOWLIST": "app,customers"
      }
    }
  }
}

모델이 변경 작업을 실제로 수행하게 하려는 경우에만 KEYCLOAK_MODE를 read-write로 올리고(삭제 작업은 admin + KEYCLOAK_ALLOW_DELETE=true) 설정하세요.

개발

npm run dev        # watch mode
npm test           # unit tests for the security policy
npm run typecheck

배포

이 서버는 공식 MCP 레지스트리용으로 server.json을, npm 소유권 인증용으로 mcpName을 제공합니다. npm 배포와 MCP 레지스트리, Smithery, Glama, Cursor, PulseMCP 등록 방법은 PUBLISHING.md 를 참조하세요.

라이선스

MIT