AI导哈

Keycloak管理协议服务器

一个提供自然语言接口的MCP服务器，用于通过REST API管理Keycloak身份和访问控制，支持用户管理、客户端配置、领域管理和角色访问控制等功能。

  • by xuancanhit99
  • Python
  • 本地部署
  • 更新于
在 GitHub 查看 xuancanhit99/mcp-keycloak

使用说明

Keycloak MCP服务器

一种模型上下文协议（MCP）服务器，它提供了一个自然语言接口，用于通过其REST API管理密钥斗篷标识和访问管理。此服务器使AI代理能够无缝执行用户管理、客户端配置、领域管理和基于角色的访问控制操作。

概述

Keycloak MCP服务器弥合了人工智能应用程序和Keycloak强大的身份管理功能之间的差距。无论您是在构建需要管理用户、配置客户端或处理复杂授权场景的AI助手，该服务器都可以通过简单的自然语言命令提供您所需的工具。

特性

🔐 全面的用户管理

管理从创建到删除的用户生命周期，包括密码重置、会话管理和用户属性更新。

🏢 客户端配置

创建和配置OAuth2/OIDC客户端，管理客户端机密，并以编程方式处理服务帐户。

👥 基于角色的访问控制

定义和分配领域和客户端特定的角色，管理用户权限，并实现细粒度的访问控制。

🏛️ 领域管理

配置领域设置、管理默认组、处理事件配置和控制领域范围的策略。

🔐 认证管理

全面的身份验证流管理，包括创建、更新和删除流、管理执行和配置身份验证器。

🔄 群组管理

将用户组织到组中，管理组层次结构，并有效地处理基于组的权限。

安装

通过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客户端的并发连接
  • 集成灵活性：易于与web应用程序和API集成
  • 负载均衡：部署在反向代理后面以实现可扩展性

HTTP协议详细信息

HTTP传输遵循可流式HTTP的MCP规范。FastMCP自动处理所有协议要求：

  • 端点：所有沟通都是通过 /mcp/ 端点
  • 请求方法：带有JSON-RPC 2.0消息的POST请求
  • 内容类型:
    • 服务器返回 Content-Type: application/json 对于单一回复
    • 服务器返回 Content-Type: text/event-stream 用于流式响应
  • 接受头：客户必须包括 Accept: application/json, text/event-stream
  • 消息格式：所有消息都使用JSON-RPC 2.0格式，UTF-8编码

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重新绑定攻击
  • 仅允许来自以下位置的连接 localhost 和 127.0.0.1 起源
  • 阻止未经授权的跨源请求

✅ 本地主机绑定（推荐）

  • 绑定到 127.0.0.1 仅用于防止基于网络的攻击
  • 遵循MCP规范安全建议

✅ 不要求进行验证

  • 服务器无需身份验证即可运行，以简化本地开发
  • 适用于本地主机使用和受信任的环境

对于生产部署，其他注意事项：

  • 使用带有适当证书的HTTPS
  • 在反向代理（nginx、Apache）后面部署
  • 设置适当的防火墙规则
  • 如果需要，在反向代理级别实施身份验证

集成示例

先决条件

在集成Keycloak MCP服务器之前，请确保安装了以下设备之一：

  • uvx （推荐）：通过安装 pip install uvx 或 pipx install uvx
  • 紫外线：关注 安装说明
  • 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
  1. 添加到您的 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实例中的现有领域匹配

示例用例

🤖 人工智能身份管理

构建可以通过自然语言命令处理用户入职、权限管理和访问控制的人工智能助手。

🔄 自动用户配置

创建工作流，根据业务规则自动配置用户、分配角色和配置客户端应用程序。

📊 身份分析

查询和分析用户数据、会话信息和访问模式，以深入了解您的身份基础设施。

🚀 DevOps集成

将Keycloak管理集成到您的CI/CD管道中，允许自动配置身份服务。

需求

  • Python 3.8或更高版本
  • Keycloak服务器（用Keycloak 18+测试）
  • Keycloak领域的管理员访问权限

许可证

此项目根据MIT许可证获得许可-有关详细信息，请参阅许可证文件。

贡献

欢迎投稿！请随时提交拉取请求。

支持

有关问题、疑问或贡献，请访问 GitHub 仓库.

相关 MCP