Keycloak Mcp Server

Keycloak MCP 服务

一个功能全面的模型上下文协议（MCP）服务，将 Keycloak Admin REST API 封装为类型化的 MCP 工具。299 个工具涵盖所有 API 类别。

---

功能

• 完整的 API 覆盖范围：涵盖全部 299 个 Keycloak Admin REST API 端点
• 双传输方式：stdio（Claude Code）和 SSE（GitHub Copilot 及其他 MCP 客户端）
• 自动身份验证：支持密码和客户端凭据流程，并自动刷新令牌
• 无需配置工具：每个工具都具有自描述性，并提供完整的输入架构

API 类别

类别	工具
攻击检测	3
身份验证管理	38
客户端证书	6
客户端初始访问	3
客户端注册策略	1
客户端角色映射	10
客户端范围	10
客户端	33
组件	6
组	11
身份提供商	15
密钥	2
组织	13
协议映射器	14
Realm 管理	37
角色	28
按 ID 查询角色	10
范围映射	29
用户	30
总计	299

演示

（在此添加 GIF 或截图，展示 3 个真实提示词及其执行的工具！）

安装

选项 1：直接使用 uvx 运行（推荐）

使用 astral 的 uv，无需手动安装即可直接运行该服务：

uvx keycloak-mcp-server

（使用 uvx 时，可以直接传入环境变量，也可以将其保存在 MCP 配置文件中。）

选项 2：通过 pip 安装

如果你更倾向于全局安装或安装到虚拟环境中：

pip install git+https://github.com/paoloamato2/keycloak-mcp-server.git

选项 3：从源代码安装（用于开发）

git clone https://github.com/paoloamato2/keycloak-mcp-server.git
cd keycloak-mcp-server
uv pip install -e .

配置

设置环境变量（或根据 .env.example 创建 .env 文件）：

# Required
export KEYCLOAK_URL=http://localhost:8080

# Authentication - Option A: Password flow
export KEYCLOAK_ADMIN_USERNAME=admin
export KEYCLOAK_ADMIN_PASSWORD=admin

# Authentication - Option B: Client credentials flow
export KEYCLOAK_CLIENT_ID=my-client
export KEYCLOAK_CLIENT_SECRET=my-secret

# Optional
export KEYCLOAK_ADMIN_REALM=master    # default: master
export KEYCLOAK_VERIFY_SSL=true       # default: true

使用方法

Claude Code（stdio）

将其添加到 Claude Code MCP 配置（~/.claude/claude_desktop_config.json 或项目级配置）：

{
  "mcpServers": {
    "keycloak": {
      "command": "python",
      "args": ["-m", "keycloak_mcp_server"],
      "env": {
        "KEYCLOAK_URL": "http://localhost:8080",
        "KEYCLOAK_ADMIN_USERNAME": "admin",
        "KEYCLOAK_ADMIN_PASSWORD": "admin"
      }
    }
  }
}

或者，如果使用 uv 安装：

{
  "mcpServers": {
    "keycloak": {
      "command": "uv",
      "args": ["run", "--directory", "/path/to/keycloak-mcp-server", "python", "-m", "keycloak_mcp_server"],
      "env": {
        "KEYCLOAK_URL": "http://localhost:8080",
        "KEYCLOAK_ADMIN_USERNAME": "admin",
        "KEYCLOAK_ADMIN_PASSWORD": "admin"
      }
    }
  }
}

GitHub Copilot（SSE）

使用 SSE 传输方式启动服务：

python -m keycloak_mcp_server --transport sse --port 8080

然后在 GitHub Copilot MCP 设置中配置（VS Code settings.json）：

{
  "github.copilot.chat.mcpServers": {
    "keycloak": {
      "type": "sse",
      "url": "http://localhost:8080/sse"
    }
  }
}

命令行

# stdio mode (default)
python -m keycloak_mcp_server

# SSE mode
python -m keycloak_mcp_server --transport sse --host 0.0.0.0 --port 8080

# Using the entry point
keycloak-mcp-server --transport sse --port 8080

安全与生产环境建议

⚠️ 安全警告： 此 MCP 服务会注册所有 Keycloak Admin REST API 端点（299 个工具），包括敏感的写入操作（例如创建／删除用户、重置密码和管理 Realm）。请勿在生产环境中使用 master Realm 的超级管理员凭据。

将此 MCP 服务连接到 AI 助手时，请严格遵循最小权限原则：

1. 使用服务账户（客户端凭据流）： 避免使用密码流（KEYCLOAK_ADMIN_USERNAME / KEYCLOAK_ADMIN_PASSWORD）。请改为创建一个启用了服务账户的专用 Keycloak 客户端，并使用 KEYCLOAK_CLIENT_ID 和 KEYCLOAK_CLIENT_SECRET。

2. 限制目标 Realm： 除非确有必要，否则不要将服务连接到 master Realm。将 KEYCLOAK_ADMIN_REALM 指向 AI 助手应管理的确切 Realm。

3. 仅授予所需角色： 只为 MCP 服务账户分配最低限度的必要角色。

   • 如果你的大模型只需要读取数据：仅分配 view-users、view-clients 或 view-realm。
   • 如果你的大模型需要管理用户：仅分配 manage-users。
   • 除非你完全了解风险，否则绝不要向 AI 分配 admin 或 realm-admin 角色。

4. 始终验证 SSL： 在生产环境中保持启用 KEYCLOAK_VERIFY_SSL=true，以防止中间人（MITM）攻击。只有在本地开发时才可以将其设为 false。

示例

连接后，你可以使用自然语言与 Keycloak 交互：

• “列出所有 Realm” → 调用 list_realms
• “在 master Realm 中创建一个名为 john 的用户” → 调用 create_user
• “显示 production Realm 中的所有客户端” → 调用 list_clients
• “用户 X 有哪些角色？” → 调用 get_user_role_mappings
• “将 admin 角色添加到 developers 组” → 调用 add_group_realm_role_mappings

项目结构

src/keycloak_mcp_server/
├── __init__.py          # Package entry point
├── __main__.py          # CLI entry point
├── config.py            # Environment-based configuration
├── client.py            # Async HTTP client with auto-auth
├── server.py            # MCP server setup and tool registration
└── endpoints/           # Endpoint definitions by category
    ├── __init__.py      # Base classes (EndpointDef, Param)
    ├── attack_detection.py
    ├── authentication.py
    ├── certificates.py
    ├── client_initial_access.py
    ├── client_registration_policy.py
    ├── client_role_mappings.py
    ├── client_scopes.py
    ├── clients.py
    ├── component.py
    ├── groups.py
    ├── identity_providers.py
    ├── key.py
    ├── organizations.py
    ├── protocol_mappers.py
    ├── realms.py
    ├── roles.py
    ├── roles_by_id.py
    ├── scope_mappings.py
    └── users.py

许可证

MIT