使用说明
Keycloak MCP服务器
全面的 模型上下文协议 用于Keycloak管理的（MCP）服务器。提供 13个领域的134个工具 --管理领域、用户、组、客户端、角色、身份提供者、身份验证流等，所有这些都可以通过您的AI助手完成。
由以下人员建造和维护 MnemoShare --符合HIPAA标准的安全文件传输平台。
特性
- 134管理工具 涵盖完整的密钥斗篷管理REST API
- 两种运输方式 --stdio（用于Claude Code、Cursor等）和HTTP（用于远程/容器部署）
- 两种身份验证模式 --管理员密码或客户端凭据（服务帐户）
- 自动令牌刷新 --透明地处理Keycloak令牌生命周期
- 零配置文件 --一切都通过环境变量
- 单个二进制 --无运行时依赖关系
快速开始
从发布版本安装
从下载最新二进制文件 发布 对于您的平台：
| 平台 | 二进制 |
|---|---|
| macOS苹果硅 | keycloak-mcp-darwin-arm64 |
| macOS英特尔 | keycloak-mcp-darwin-amd64 |
| Linux x86_64 | keycloak-mcp-linux-amd64 |
chmod +x keycloak-mcp-*
mv keycloak-mcp-* /usr/local/bin/keycloak-mcp
从源代码构建
git clone https://github.com/MnemoShare/mnemoshare-keycloak-mcp.git
cd mnemoshare-keycloak-mcp
make build
配置
所有配置都是通过环境变量进行的：
| 变量 | 必填 | 默认 | 描述 |
|---|---|---|---|
TRANSPORT |
没有 | stdio |
运输方式： stdio 或 http |
PORT |
没有 | 8080 |
HTTP端口（仅限HTTP模式） |
KEYCLOAK_URL |
是 | -- | 密钥斗篷基本URL（例如。 https://id.example.com) |
KEYCLOAK_REALM |
没有 | master |
身份验证领域 |
KEYCLOAK_AUTH_MODE |
没有 | password |
身份验证模式： password 或 client_credentials |
KEYCLOAK_ADMIN_USER |
密码模式 | -- | 管理员用户名 |
KEYCLOAK_ADMIN_PASSWORD |
密码模式 | -- | 管理员密码 |
KEYCLOAK_CLIENT_ID |
对于client_credentials | -- | 服务帐户客户端ID |
KEYCLOAK_CLIENT_SECRET |
对于client_credentials | -- | 服务帐户客户端密码 |
KEYCLOAK_DEFAULT_REALM |
否 | -- | 工具操作的默认领域 |
LOG_LEVEL |
没有 | info |
日志级别： debug, info, warn, error |
LOG_FORMAT |
没有 | json |
日志格式： json 或 console |
用法
克劳德代码
添加一个 .mcp.json 将文件保存到项目根目录：
{
"mcpServers": {
"keycloak": {
"command": "keycloak-mcp",
"env": {
"KEYCLOAK_URL": "https://id.example.com",
"KEYCLOAK_AUTH_MODE": "client_credentials",
"KEYCLOAK_CLIENT_ID": "mcp-admin",
"KEYCLOAK_CLIENT_SECRET": "your-secret-here",
"KEYCLOAK_DEFAULT_REALM": "your-realm"
}
}
}
}
或者在开发过程中从源代码运行：
{
"mcpServers": {
"keycloak": {
"command": "go",
"args": ["run", "./cmd/server"],
"cwd": "/path/to/mnemoshare-keycloak-mcp",
"env": {
"KEYCLOAK_URL": "https://id.example.com",
"KEYCLOAK_AUTH_MODE": "client_credentials",
"KEYCLOAK_CLIENT_ID": "mcp-admin",
"KEYCLOAK_CLIENT_SECRET": "your-secret-here",
"KEYCLOAK_DEFAULT_REALM": "your-realm"
}
}
}
}
HTTP模式
使用HTTP传输运行以公开可流式传输的HTTP端点，这对容器化或远程部署很有用：
TRANSPORT=http KEYCLOAK_URL=https://id.example.com make run-http
终点：
GET /health--健康检查POST /mcp--MCP可流式HTTP端点
码头工人
make docker-build
docker run -e KEYCLOAK_URL=https://id.example.com \
-e KEYCLOAK_AUTH_MODE=client_credentials \
-e KEYCLOAK_CLIENT_ID=mcp-admin \
-e KEYCLOAK_CLIENT_SECRET=your-secret \
keycloak-mcp:latest
钥匙斗篷设置
选项1：带密码模式的Bootstrap（新安装）
在新的Keycloak实例上，您还没有服务帐户。从密码模式开始，这样你的AI助手就可以连接并为你创建一个密码模式：
{
"mcpServers": {
"keycloak": {
"command": "keycloak-mcp",
"env": {
"KEYCLOAK_URL": "https://id.example.com",
"KEYCLOAK_AUTH_MODE": "password",
"KEYCLOAK_ADMIN_USER": "admin",
"KEYCLOAK_ADMIN_PASSWORD": "your-admin-password",
"KEYCLOAK_DEFAULT_REALM": "your-realm"
}
}
}
}
连接后，让您的AI助手：
- 创建机密客户（例如。
mcp-admin)在 大师 领域 - 分配
admin域角色到其服务帐户 - 检索客户端密钥
然后切换到客户端凭据模式（选项2），并从配置中删除管理员密码。
选项2：客户端凭据模式（推荐）
对于日常使用，请配置服务帐户客户端。要在Keycloak管理控制台中手动设置它：
- 首选 大师 领域> 客户 > 创建客户端
- 设置客户端ID（例如。
mcp-admin)，启用 客户端认证 - 在...之下 服务帐户角色，分配
admin领域角色 - 从复制客户端密钥 凭证 标签
这对于持续使用来说更安全——服务帐户有一个可旋转的秘密，不会暴露您的管理员凭据。
工具
13个领域的134个工具：
| 域 | 工具 | 描述 |
|---|---|---|
| 领域 | 8 | 列出、获取、创建、更新、删除、清除缓存 |
| 用户 | 24 | CRUD、密码、凭据、组、会话、联合身份、角色 |
| 群组 | 12 | CRUD、成员、计数、领域/客户端角色映射 |
| 客户 | 18 | CRUD、机密、服务帐户、作用域、协议映射器、会话 |
| 角色 | 16 | 领域+客户端角色CRUD、复合、用户/组查找 |
| 身份提供者 | 8 | CRUD+映射器 |
| 身份验证流程 | 10 | 流程、执行、所需行动 |
| 客户范围 | 10 | CRUD+协议映射器+领域默认值 |
| 会话 | 5 | 注销、事件、离线会话、撤销同意 |
| 授权 | 15 | 资源、范围、策略、权限 |
| 组件 | 5 | 用户联合、LDAP、自定义提供者的CRUD |
| 攻击检测 | 2 | 暴力状态+清除 |
| 察看连接信息 | 1 | Keycloak服务器信息 |
贡献
欢迎投稿！请打开问题或提交拉取请求。
- 分叉存储库
- 创建功能分支(
git checkout -b feature/my-feature) - 提交您的更改(
git commit -am 'Add my feature') - 推到分支(
git push origin feature/my-feature) - 打开拉取请求
许可证
该项目根据MIT许可证获得许可——请参阅 许可证 文件以获取详细信息。
关于MnemoShare
MnemoShare 是一个符合HIPAA标准、HITRUST认证的安全文件传输平台。我们构建了这个MCP服务器来管理我们自己的Keycloak基础设施，并将其与社区共享，因为我们相信人工智能驱动的管理应该对每个人开放。
