Keycloak MCP Server

一个用于 Keycloak 的 MCP 服务

Keycloak MCP 服务

一个模型上下文协议（MCP）服务，可通过编程方式访问 Keycloak 管理功能。

概述

Keycloak MCP 服务使 AI 助手和开发工具能够通过模型上下文协议与 Keycloak 交互。它支持全面的 Keycloak 操作，包括用户管理、领域配置、客户端管理和身份验证流程管理。

主要功能

• 用户 JWT 令牌身份验证
• 全面的 Keycloak 操作（用户、领域、客户端、角色、组等）
• 基于 HTTP 通信的 SSE 传输
• 可用于生产环境的 OpenShift/Kubernetes 部署
• 多架构容器映像
• 支持 GraalVM 原生映像

快速开始

使用 Docker

docker run -d \
  --name keycloak-mcp-server \
  -p 8080:8080 \
  -e KC_URL=https://keycloak.example.com \
  -e KC_REALM=master \
  -e OIDC_CLIENT_ID=mcp-server \
  quay.io/sshaaf/keycloak-mcp-server:latest

身份验证

用户使用自己从 Keycloak 获取的 JWT 令牌进行身份验证：

# Get your token
./scripts/get-mcp-token.sh \
  --keycloak-url https://keycloak.example.com \
  --username your-username \
  --password your-password

在 MCP 客户端中配置（~/.cursor/mcp.json）：

{
  "mcpServers": {
    "keycloak": {
      "transport": "sse",
      "url": "https://mcp-server.example.com/mcp/sse",
      "headers": {
        "Authorization": "Bearer <your-jwt-token>"
      }
    }
  }
}

文档

完整文档位于 docs 目录中：

• 入门指南 - 设置说明
• 身份验证指南 - 用户身份验证
• OpenShift 部署 - 生产环境部署
• 开发者指南 - 开发指南
• 完整文档索引 - 完整目录

构建文档

本项目使用 MkDocs 编写文档。要在本地构建并提供文档服务：

pip install mkdocs-material
mkdocs serve

访问 http://localhost:8000 查看文档。

容器映像

可从 Quay.io 获取预构建映像：

docker pull quay.io/sshaaf/keycloak-mcp-server:latest

每次向 main 分支提交代码以及发布版本时，都会自动构建并推送映像。

构建

JAR

mvn clean package
java -jar target/quarkus-app/quarkus-run.jar

原生映像

mvn clean package -Pnative
./target/keycloak-mcp-server-runner

容器映像

mvn clean package -Dquarkus.container-image.build=true

测试

• 默认单元测试和集成测试：mvn test
• 提示词 / 评估覆盖率说明：evals/README.md

技术栈

• Quarkus - 云原生 Java 框架
• Keycloak Admin Client - Keycloak 官方 Java 客户端
• MCP Protocol - 用于 AI 集成的模型上下文协议
• Jib - 无需 Docker 守护进程即可构建容器映像
• GraalVM - 支持原生映像编译

许可证

MIT 许可证 - 详情请参阅 LICENSE 文件。

贡献

欢迎贡献。详情请参阅贡献者指南。

支持

• 文档：docs/index.md
• 问题：GitHub Issues
• 社区：Keycloak Discourse

---

维护者：Shaaf Syed
仓库：https://github.com/sshaaf/keycloak-mcp-server
容器注册表：https://quay.io/repository/sshaaf/keycloak-mcp-server