Keycloak AI集成入口

钥匙斗篷MCP入口点

AI工具的入口点包装器，通过模型上下文协议（MCP）与Keycloak集成。

概述

该软件包为AI助手（如Claude Desktop）与Keycloak交互提供了一个简化的入口点。它加载环境配置并启动 另一款钥匙斗篷mcp 服务器自动。

快速开始

1.安装依赖项

npm install

2.配置环境

复制示例环境文件并对其进行配置：

cp .env.example .env

编辑 .env 使用您的Keycloak连接详细信息：

# Keycloak Server Configuration
# IMPORTANT: Use 'localhost' or '127.0.0.1', not '0.0.0.0'
# For legacy Keycloak (<17) use: http://localhost:8082/auth
# For modern Keycloak (>=17) use: http://localhost:8082
KEYCLOAK_URL=http://localhost:8082/auth
KEYCLOAK_REALM=my-realm

# Authentication Method 1 (Recommended): Client Credentials
# Use a dedicated OIDC client with service account enabled
KEYCLOAK_CLIENT_ID=sso-admin-mcp
KEYCLOAK_CLIENT_SECRET=test12345

# Authentication Method 2 (Alternative): Admin User Credentials
# Note: Some Keycloak setups may not allow password grant type
# KEYCLOAK_ADMIN_USERNAME=admin
# KEYCLOAK_ADMIN_PASSWORD=admin

# Operation Mode: development | production
OPERATION_MODE=development

# Read-Only Mode: true | false
READ_ONLY_MODE=false

# Transport: stdio | http
TRANSPORT=stdio

# Logging Level: error | warn | info | debug
LOG_LEVEL=info

3.建设项目

npm run build

4.跑步

npm start

或者直接使用二进制文件：

node dist/index.js

AI工具集成

此MCP服务器可以与支持模型上下文协议的各种AI工具集成。

光标集成

创建或编辑 .cursor/mcp.json 在您的项目目录中：

{
  "mcpServers": {
    "keycloak": {
      "command": "node",
      "args": [
        "/absolute/path/to/keycloak-mcp-entrypoint/dist/index.js"
      ]
    }
  }
}

重要：将路径替换为实际的绝对路径。

配置后：

1. 保存 mcp.json 文件
2. 完全重新启动游标
3. Keycloak工具应出现在Cursor的AI上下文中
4. 现在，您可以要求Cursor执行Keycloak操作（例如，“列出acme-x领域中的所有用户”）

Claude桌面集成

将以下配置添加到Claude Desktop配置文件中。

配置文件位置：

• macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
• 视窗: %APPDATA%\Claude\claude_desktop_config.json
• Linux: ~/.config/Claude/claude_desktop_config.json

macOS示例

编辑 ~/Library/Application Support/Claude/claude_desktop_config.json:

{
  "mcpServers": {
    "keycloak": {
      "command": "node",
      "args": [
        "/absolute/path/to/keycloak-mcp-entrypoint/dist/index.js"
      ]
    }
  }
}

重要：将路径替换为实际的绝对路径。要获取当前目录路径，请运行：

cd /path/to/keycloak-mcp-entrypoint
pwd

Windows示例

编辑 %APPDATA%\Claude\claude_desktop_config.json:

{
  "mcpServers": {
    "keycloak": {
      "command": "node",
      "args": [
        "C:\\Users\\YourUsername\\Documents\\keycloak-mcp-entrypoint\\dist\\index.js"
      ]
    }
  }
}

配置后

1. 保存配置文件
2. 完全退出并重新启动Claude Desktop（而不仅仅是重新加载）
3. 打开新对话
4. 在工具面板（锤子图标）中查找Keycloak MCP工具
5. 您应该看到所有可用的45个Keycloak管理工具

环境变量

密钥斗篷URL格式

这 KEYCLOAK_URL 格式取决于您的Keycloak版本：

• 传统钥匙斗篷（<17） 或 红帽SSO：使用 http://localhost:8082/auth
• 现代钥匙斗篷（>=17）：使用 http://localhost:8082

重要：始终使用 localhost 或 127.0.0.1 对于客户端URL，不是 0.0.0.0.虽然 0.0.0.0 对于服务器绑定有效，它不是HTTP客户端的有效目标。

身份验证方法

MCP服务器支持两种身份验证方法：

方法1：客户端凭据（推荐）

这是 推荐方法 用于服务到服务的身份验证。MCP服务器将使用OIDC客户端凭据流。

要求：

1. 在Keycloak中创建专用的OIDC客户端（例如。， sso-admin-mcp)
2. 为客户端启用“服务帐户”
3. 为服务帐户分配适当的角色：
   • 前往客户处→ “服务帐户角色”选项卡
   • 分配 realm-management 角色（例如。， view-users, manage-users, view-realm等等）

配置：

KEYCLOAK_CLIENT_ID=sso-admin-mcp
KEYCLOAK_CLIENT_SECRET=test12345

优势：

• 比用户名/密码更安全
• 禁用密码授权类型时有效
• 更适合服务客户
• 支持令牌刷新

方法2：用户名/密码（可选）

使用具有密码授权类型的管理员用户名和密码。如果您的Keycloak配置出于安全原因禁用了密码授予类型，则这可能不起作用。

配置：

KEYCLOAK_ADMIN_USERNAME=admin
KEYCLOAK_ADMIN_PASSWORD=admin
# Leave CLIENT_SECRET empty to use this method

备注：如果同时提供了客户端凭据和用户名/密码，则将使用客户端凭据（优先）。

特性

此入口点允许从另一个keycloak mcp访问所有45个工具：

• 用户管理 （13个工具）：创建、读取、更新、删除用户、管理属性、检查多个帐户、验证IDP链接
• 组管理 （16个工具）：完整的CRUD、层次结构管理、属性搜索、布尔切换
• 领域操作 （3个工具）：列出、阅读和获取领域的统计数据
• 认证 （3个工具）：管理身份验证流程和所需操作
• 领域工具 （3个工具）：导出领域，检查SAML证书，列出自定义SPI
• 客户范围 （7个工具）：用于客户端范围管理的完整CRUD

安全功能

• 操作模式：磨合 development 或 production 具有不同安全级别的模式
• 只读模式：启用时阻止所有写入操作
• 安全检查：所有破坏性操作都包括安全警告和检查
• 验证：所有输入均已Zod模式验证
• 自动令牌刷新：Keycloak访问令牌在过期前会自动刷新，以防止身份验证失败

发展

可用脚本

• npm run build -构建项目
• npm run dev -内置手表模式
• npm start -运行构建的入口点
• npm run clean -清理dist文件夹
• npm run type-check -运行TypeScript类型检查

项目结构

keycloak-mcp-entrypoint/
├── src/
│   └── index.ts          # Entry point script
├── dist/                 # Built output
├── .env                  # Your configuration (not committed)
├── .env.example          # Example configuration
├── package.json          # Project dependencies
├── tsconfig.json         # TypeScript configuration
└── tsup.config.ts        # Build configuration

故障排除

连接问题

如果无法连接到Keycloak：

1. 验证Keycloak是否正在运行:

   复制

   curl http://localhost:8082/auth/realms/master/.well-known/openid-configuration
   

   您应该看到一个带有Keycloak配置的JSON响应。

2. 检查你的 .env 文件具有正确的 KEYCLOAK_URL:

   • 使用 localhost 或 127.0.0.1，不 0.0.0.0
   • 对于传统Keycloak（<17）： http://localhost:8082/auth
   • 对于现代Keycloak（>=17）： http://localhost:8082

3. 验证管理员凭据是否正确:

   • 检查您的Keycloak管理控制台凭据
   • 默认值通常为 admin / admin 促进地方发展

4. 检查日志以获取详细的错误消息:

   复制

   npm start
   

   在输出中查找连接错误或身份验证失败。

5. 常见错误：“无法确定错误消息”

   • 这通常意味着URL不正确（可能使用 0.0.0.0 而不是 localhost)
   • 或者 /auth 旧版Keycloak缺少路径

6. 401未经授权的错误:

   • MCP服务器会自动刷新过期的令牌，但如果您仍然看到401错误：
   • 验证中的凭据 .env 是正确的
   • 检查服务帐户是否在Keycloak中分配了正确的角色
   • 确保域名拼写正确
   • 尝试重新启动MCP服务器（重新启动Cursor或Claude Desktop）

7. “未经授权的客户端”错误:

   • 这意味着客户端不支持正在使用的身份验证方法
   • 解决方案：切换到客户端凭据身份验证（方法1）
   • 确保您的Keycloak客户端已启用“服务帐户”
   • 分配适当 realm-management 角色到服务帐户
   • 更新您的 .env 使用 KEYCLOAK_CLIENT_ID 和 KEYCLOAK_CLIENT_SECRET

游标集成问题

如果Cursor未显示Keycloak工具或显示“无工具、提示或资源”：

1. 验证 .cursor/mcp.json 文件存在 在项目根目录中
2. 检查绝对路径 配置文件中正确
3. 确保项目建成: npm run build
4. 完全重新启动游标 -关闭所有窗口并重新打开
5. 检查Cursor的MCP日志 对于任何错误消息
6. 手动测试服务器:
   复制

   cd /path/to/keycloak-mcp-entrypoint
   npm start
   

   您应该看到Keycloak连接成功的消息

Claude桌面集成问题

如果Claude Desktop未显示Keycloak工具：

1. 验证中的绝对路径 claude_desktop_config.json 是正确的:

   复制

   # Get the correct path
   cd /path/to/keycloak-mcp-entrypoint
   pwd
   # Then append /dist/index.js to this path
   

2. 确保项目建成:

   复制

   npm run build
   

   验证 dist/index.js 存在。

3. 首先手动测试服务器:

   复制

   npm start
   

   在添加到Claude Desktop之前，请确保它已成功连接。

4. 完全退出并重新启动Claude Desktop （不仅仅是重新加载）：

   • macOS：按Cmd+Q退出，然后重新打开
   • Windows：文件→ 退出，然后重新打开
   • Linux：关闭所有窗口，然后重新打开

5. 检查Claude Desktop日志是否有错误:

   • macOS： ~/Library/Logs/Claude/mcp*.log
   • 窗户： %APPDATA%\Claude\logs\mcp*.log
   • Linux： ~/.config/Claude/logs/mcp*.log

6. 验证JSON语法是否正确:

   • 使用JSON验证器检查配置文件
   • 确保没有尾随逗号
   • 确保正确的引号转义（特别是在Windows路径上：使用 \\)

构建问题

如果构建失败：

1. 确保 another-keycloak-mcp 已建成： cd ../another-keycloak-mcp && npm run build
2. 清理和重建： npm run clean && npm install && npm run build
3. 检查Node.js版本： node --version （要求>=18.0.0）

许可证

麻省理工学院