Keycloak MCP 서버

Keycloak REST API를 통해 Keycloak ID 및 액세스 관리를 위한 자연어 인터페이스를 제공하는 MCP(Model Context Protocol) 서버입니다. 이 서버를 통해 AI 에이전트는 사용자 관리, 클라이언트 구성, 영역(realm) 관리 및 역할 기반 액세스 제어 작업을 원활하게 수행할 수 있습니다.

개요

Keycloak MCP 서버는 AI 애플리케이션과 Keycloak의 강력한 ID 관리 기능 사이의 가교 역할을 합니다. 사용자를 관리하거나, 클라이언트를 구성하거나, 복잡한 권한 부여 시나리오를 처리해야 하는 AI 어시스턴트를 구축할 때, 이 서버는 간단한 자연어 명령을 통해 필요한 도구를 제공합니다.

Related MCP server: Advanced Keycloak MCP server

기능

🔐 포괄적인 사용자 관리

생성부터 삭제까지 사용자 수명 주기를 관리하며, 비밀번호 재설정, 세션 관리 및 사용자 속성 업데이트를 포함합니다.

🏢 클라이언트 구성

OAuth2/OIDC 클라이언트를 생성 및 구성하고, 클라이언트 시크릿을 관리하며, 서비스 계정을 프로그래밍 방식으로 처리합니다.

👥 역할 기반 액세스 제어

영역 및 클라이언트별 역할을 정의 및 할당하고, 사용자 권한을 관리하며, 세밀한 액세스 제어를 구현합니다.

🏛️ 영역(Realm) 관리

영역 설정을 구성하고, 기본 그룹을 관리하며, 이벤트 구성을 처리하고, 영역 전체 정책을 제어합니다.

🔐 인증 관리

인증 흐름 생성, 업데이트, 삭제, 실행 관리 및 인증자 구성을 포함한 포괄적인 인증 흐름 관리 기능을 제공합니다.

🔄 그룹 관리

사용자를 그룹으로 구성하고, 그룹 계층 구조를 관리하며, 그룹 기반 권한을 효율적으로 처리합니다.

설치

Smithery를 통한 설치

Smithery를 통해 Claude Desktop용 mcp-keycloak을 자동으로 설치하려면:

npx -y @smithery/cli install mcp-keycloak --client claude

빠른 시작

pip을 사용하여 설치:

pip install mcp-keycloak

개발 설치

저장소를 복제하고 종속성을 설치합니다:

git clone https://github.com/idoyudha/mcp-keycloak.git
cd mcp-keycloak
pip install -e .

구성

서버는 환경 변수나 .env 파일을 사용하여 구성할 수 있습니다:

# Required configuration
SERVER_URL=https://your-keycloak-server.com
USERNAME=admin-username
PASSWORD=admin-password
REALM_NAME=your-realm

# Optional OAuth2 client configuration
CLIENT_ID=optional-client-id
CLIENT_SECRET=optional-client-secret

도구

Keycloak MCP 서버는 기능별로 구성된 포괄적인 도구 세트를 제공합니다:

사용자 관리

다음과 같은 전체 사용자 수명 주기 관리:

• list_users - 페이지 매김 및 필터링을 사용하여 사용자 목록 표시

• create_user / update_user / delete_user - 전체 CRUD 작업

• reset_user_password - 비밀번호 관리

• get_user_sessions / logout_user - 세션 제어

• count_users - 사용자 통계

클라이언트 관리

OAuth2/OIDC 클라이언트 구성:

• list_clients / get_client / create_client - 클라이언트 작업

• get_client_secret / regenerate_client_secret - 시크릿 관리

• get_client_service_account - 서비스 계정 액세스

• update_client / delete_client - 클라이언트 수정

역할 관리

세밀한 권한 제어:

• list_realm_roles / create_realm_role - 영역 역할 작업

• list_client_roles / create_client_role - 클라이언트별 역할

• assign_realm_role_to_user / remove_realm_role_from_user - 역할 할당

• get_user_realm_roles / assign_client_role_to_user - 사용자 역할 쿼리

그룹 관리

계층적 사용자 구성:

• list_groups / create_group / update_group - 그룹 작업

• get_group_members / add_user_to_group - 멤버십 관리

• get_user_groups / remove_user_from_group - 사용자 그룹 연결

영역 관리

시스템 전체 구성:

• get_accessible_realms - 액세스 가능한 영역 목록

• get_realm_info / update_realm_settings - 영역 구성

• get_realm_events_config / update_realm_events_config - 이벤트 관리

• add_realm_default_group / remove_realm_default_group - 기본 설정

인증 관리

전체 인증 흐름 제어:

• list_authentication_flows / get_authentication_flow - 흐름 관리

• create_authentication_flow / update_authentication_flow - 흐름 CRUD 작업

• delete_authentication_flow / copy_authentication_flow - 흐름 수정

• get_flow_executions / update_flow_executions - 실행 관리

• create_execution / delete_execution - 실행 수명 주기

• get_authenticator_config / create_authenticator_config - 구성 관리

• get_required_actions / update_required_action - 필수 작업 제어

사용법

서버 실행

서버는 stdio(기본값) 및 HTTP 전송을 모두 지원합니다. smithery.yaml 구성 파일은 Smithery 플랫폼에서의 배포와 Smithery CLI를 통한 자동 설치를 가능하게 합니다:

# Run in stdio mode (default, for local CLI tools)
python -m src.main

# Run in HTTP mode with streamable HTTP transport
TRANSPORT=http python -m src.main

# Run HTTP mode on a custom port
TRANSPORT=http PORT=8080 python -m src.main

# Or use the convenience script:
./scripts/run_server.sh         # stdio mode (default)
./scripts/run_server.sh http    # HTTP mode
PORT=8080 ./scripts/run_server.sh http  # HTTP mode on custom port

HTTP 전송을 사용할 경우, 서버는 http://127.0.0.1:8000/mcp/(또는 사용자 지정 포트)에서 액세스할 수 있습니다.

HTTP 전송

Keycloak MCP 서버는 다음과 같은 여러 이점을 제공하는 HTTP 전송 모드를 지원합니다:

• 네트워크 접근성: 네트워크상의 모든 기기에서 서버에 액세스

• 다중 클라이언트: 여러 AI 클라이언트로부터의 동시 연결 지원

• 통합 유연성: 웹 애플리케이션 및 API와의 쉬운 통합

• 로드 밸런싱: 확장성을 위해 리버스 프록시 뒤에 배포

HTTP 프로토콜 세부 정보

HTTP 전송은 Streamable HTTP에 대한 MCP 사양을 따릅니다. FastMCP는 모든 프로토콜 요구 사항을 자동으로 처리합니다:

• 엔드포인트: 모든 통신은 /mcp/ 엔드포인트를 통해 이루어집니다.

• 요청 메서드: JSON-RPC 2.0 메시지를 포함한 POST 요청

• 콘텐츠 유형:

  • 서버는 단일 응답에 대해 Content-Type: application/json을 반환합니다.

  • 서버는 스트리밍 응답에 대해 Content-Type: text/event-stream을 반환합니다.

• Accept 헤더: 클라이언트는 Accept: application/json, text/event-stream을 포함해야 합니다.

• 메시지 형식: 모든 메시지는 UTF-8로 인코딩된 JSON-RPC 2.0 형식을 사용합니다.

FastMCP는 요청 유형과 응답에 스트리밍 기능이 필요한지 여부에 따라 단일 JSON 응답을 반환할지 SSE 스트림을 반환할지 자동으로 결정합니다.

HTTP 서버에 연결

HTTP 모드에서 실행할 때 클라이언트는 다음 주소로 연결할 수 있습니다:

http://127.0.0.1:8000/mcp/

클라이언트 요청 예시:

curl -X POST http://localhost:8000/mcp/ \
  -H "Content-Type: application/json" \
  -H "Accept: application/json, text/event-stream" \
  -d '{"jsonrpc": "2.0", "method": "list_tools", "id": 1}'

보안 구현

HTTP 전송은 모든 MCP 사양 보안 요구 사항을 구현합니다:

✅ Origin 헤더 유효성 검사 (필수)

• DNS 리바인딩 공격을 방지하기 위해 Origin 헤더를 자동으로 검사합니다.

• localhost 및 127.0.0.1 오리진에서의 연결만 허용합니다.

• 승인되지 않은 교차 오리진 요청을 차단합니다.

✅ Localhost 바인딩 (권장)

• 네트워크 기반 공격을 방지하기 위해 127.0.0.1에만 바인딩합니다.

• MCP 사양 보안 권장 사항을 따릅니다.

✅ 인증 불필요

• 서버는 간소화된 로컬 개발을 위해 인증 요구 사항 없이 실행됩니다.

• localhost 사용 및 신뢰할 수 있는 환경에 적합합니다.

프로덕션 배포의 경우 추가 고려 사항:

• 적절한 인증서와 함께 HTTPS 사용

• 리버스 프록시(nginx, Apache) 뒤에 배포

• 적절한 방화벽 규칙 설정

• 필요한 경우 리버스 프록시 수준에서 인증 구현

통합 예시

사전 요구 사항

Keycloak MCP 서버를 통합하기 전에 다음 중 하나가 설치되어 있는지 확인하십시오:

• uvx (권장): pip install uvx 또는 pipx install uvx를 통해 설치

• uv: 설치 지침을 따르십시오.

• npm/npx: Smithery 설치용 (Node.js와 함께 제공)

옵션 1: Smithery CLI 사용 (권장)

가장 쉬운 방법으로, Claude Desktop을 위해 모든 것을 자동으로 구성합니다:

npx @smithery/cli install @idoyudha/mcp-keycloak --client claude

이 명령은 필요한 구성 값을 묻고 서버를 자동으로 설정합니다.

옵션 2: uvx 사용 (수동 설정)

복제할 필요가 없습니다! claude_desktop_config.json에 추가하십시오:

{
  "mcpServers": {
    "keycloak": {
      "command": "uvx",
      "args": ["mcp-keycloak"],
      "env": {
        "SERVER_URL": "https://your-keycloak.com",
        "USERNAME": "admin",
        "PASSWORD": "admin-password",
        "REALM_NAME": "your-realm"
      }
    }
  }
}

옵션 3: 로컬 개발 설정

개발 또는 사용자 지정을 위한 설정:

1. 저장소 복제:

git clone https://github.com/idoyudha/mcp-keycloak.git
cd mcp-keycloak

2. claude_desktop_config.json에 추가:

{
  "mcpServers": {
    "keycloak": {
      "command": "uv",
      "args": [
        "--directory",
        "/path/to/mcp-keycloak",
        "run",
        "python",
        "-m",
        "src"
      ],
      "env": {
        "SERVER_URL": "https://your-keycloak.com",
        "USERNAME": "admin",
        "PASSWORD": "admin-password",
        "REALM_NAME": "your-realm"
      }
    }
  }
}

💡 빠른 팁:

• /path/to/mcp-keycloak을 저장소를 복제한 실제 경로로 바꾸십시오.

• Keycloak 서버 URL에 프로토콜(https:// 또는 http://)이 포함되어 있는지 확인하십시오.

• REALM_NAME은 Keycloak 인스턴스에 존재하는 영역과 일치해야 합니다.

사용 사례 예시

🤖 AI 기반 ID 관리

자연어 명령을 통해 사용자 온보딩, 권한 관리 및 액세스 제어를 처리할 수 있는 AI 어시스턴트를 구축하십시오.

🔄 자동화된 사용자 프로비저닝

비즈니스 규칙에 따라 사용자를 자동으로 프로비저닝하고, 역할을 할당하며, 클라이언트 애플리케이션을 구성하는 워크플로우를 만드십시오.

📊 ID 분석

사용자 데이터, 세션 정보 및 액세스 패턴을 쿼리하고 분석하여 ID 인프라에 대한 통찰력을 얻으십시오.

🚀 DevOps 통합

Keycloak 관리를 CI/CD 파이프라인에 통합하여 ID 서비스의 자동화된 구성을 가능하게 하십시오.

요구 사항

• Python 3.8 이상

• Keycloak 서버 (Keycloak 18+에서 테스트됨)

• Keycloak 영역에 대한 관리자 액세스 권한

라이선스

이 프로젝트는 MIT 라이선스에 따라 라이선스가 부여됩니다. 자세한 내용은 LICENSE 파일을 참조하십시오.

기여

기여를 환영합니다! 자유롭게 Pull Request를 제출해 주십시오.

지원

문제, 질문 또는 기여에 대해서는 GitHub 저장소를 방문해 주십시오.