内容
# mcp-freeipa
MCP 服务器，用于 [FreeIPA](https://www.freeipa.org/) / [Red Hat IdM](https://www.redhat.com/en/technologies/management/identity-manager) — 通过模型上下文协议进行用户、组、主机、DNS、HBAC 和 sudo 管理。
## 功能特点
- **用户** — 列出、获取、创建、启用、禁用、删除和重置密码
- **组** — 列出、获取和管理组成员资格
- **主机** — 列出和检查已注册的主机
- **DNS** — 列出区域，列出和获取记录（A、AAAA、CNAME、MX、PTR、TXT、SRV 等）
- **Sudo 规则** — 列出和检查 sudo 策略规则
- **HBAC 规则** — 列出和检查基于主机的访问控制规则
## 要求
- FreeIPA 4.6+ 或 Red Hat IdM 7.6+（任何具有 JSON-RPC API 的现代版本）
- Node.js 18+
- 管理帐户或具有对相关对象读取权限的专用服务帐户
### FreeIPA 权限
所需的最低权限取决于您使用的工具：
| 区域 | 所需权限 |
|---|---|
| 用户 | `用户管理员` 角色或 `系统：读取用户` 权限 |
| 组 | `组管理员` 角色或 `系统：读取组` 权限 |
| 主机 | `主机管理员` 角色或 `系统：读取主机` 权限 |
| DNS | `DNS 管理员` 角色或 `系统：读取 DNS 条目` 权限 |
| Sudo | `Sudo 管理员` 角色或 `系统：读取 Sudo 规则` 权限 |
| HBAC | `HBAC 管理员` 角色或 `系统：读取 HBAC 规则` 权限 |
对于只读使用，您可以创建一个专用服务帐户，并仅通过 RBAC 角色授予其 `系统：读取 *` 权限。
## 环境变量
| 变量 | 是否必需 | 默认值 | 描述 |
|---|---|---|---|
| `FREEIPA_HOST` | 是 | — | FreeIPA 服务器主机名（例如 `ipa.example.com`） |
| `FREEIPA_PASSWORD` | 是 | — | FreeIPA 帐户密码 |
| `FREEIPA_USERNAME` | 否 | `admin` | FreeIPA 帐户用户名 |
| `FREEIPA_ALLOW_SELF_SIGNED` | 否 | `true` | 允许自签名 TLS 证书（`true`/`false`） |
## 安装
```bash
npm install
npm run build
```
## Claude Desktop 配置
添加到 `claude_desktop_config.json`：
```json
{
"mcpServers": {
"freeipa": {
"command": "node",
"args": ["/absolute/path/to/mcp-freeipa/dist/index.js"],
"env": {
"FREEIPA_HOST": "ipa.example.com",
"FREEIPA_USERNAME": "admin",
"FREEIPA_PASSWORD": "your-password-here",
"FREEIPA_ALLOW_SELF_SIGNED": "true"
}
}
}
}
```
如果您已通过 `npm install -g mcp-freeipa`全局安装了软件包：
```json
{
"mcpServers": {
"freeipa": {
"command": "mcp-freeipa",
"env": {
"FREEIPA_HOST": "ipa.example.com",
"FREEIPA_USERNAME": "admin",
"FREEIPA_PASSWORD": "your-password-here"
}
}
}
}
```
## 可用工具
### 用户
| 工具 | 描述 |
|---|---|
| `list_users` | 列出用户，带有可选的 uid / cn / mail 过滤器 |
| `get_user` | 通过 UID 获取用户的完整详细信息 |
| `enable_user` | 启用禁用的用户帐户 |
| `disable_user` | 禁用（锁定）用户帐户 |
| `add_user` | 创建新的用户帐户 |
| `delete_user` | 永久删除用户帐户 |
| `reset_password` | 重置用户的密码 |
### 组
| 工具 | 描述 |
|---|---|
| `list_groups` | 列出组，带有可选的名称过滤器 |
| `get_group` | 通过名称获取组的完整详细信息 |
| `add_user_to_group` | 将一个或多个用户添加到组 |
| `remove_user_from_group` | 从组中删除一个或多个用户 |
### 主机
| 工具 | 描述 |
|---|---|
| `list_hosts` | 列出已注册的主机，带有可选的 FQDN 过滤器 |
| `get_host` | 通过 FQDN 获取主机的完整详细信息 |
### DNS
| 工具 | 描述 |
|---|---|
| `list_dns_zones` | 列出所有 DNS 区域 |
| `list_dns_records` | 列出 DNS 区域中的所有记录 |
| `get_dns_record` | 获取区域中特定名称的所有记录类型 |
### Sudo
| 工具 | 描述 |
|---|---|
| `list_sudo_rules` | 列出所有 sudo 规则 |
| `get_sudo_rule` | 获取 sudo 规则的完整详细信息 |
### HBAC
| 工具 | 描述 |
|---|---|
| `list_hbac_rules` | 列出所有基于主机的访问控制规则 |
| `get_hbac_rule` | 获取 HBAC 规则的完整详细信息 |
## FreeIPA API 说明
服务器使用 FreeIPA JSON-RPC API（`/ipa/session/json`）。它通过表单编码登录（`/ipa/session/login_password`）使用用户名和密码进行身份验证，并存储生成的 `ipa_session` cookie 以用于后续所有请求。会话 cookie 在过期时（HTTP 401）自动刷新。
FreeIPA 返回所有属性值作为数组，即使对于标量字段（例如，`{"uid": ["john"]}`）。服务器自动规范化这些，将标量字段的第一个元素提取出来，并为 `memberof_group` 等列表字段保留完整数组。
## 开发
```bash
npm run dev # 使用 tsx 运行（无构建步骤）
npm run build # 将 TypeScript 编译到 dist/
npm start # 运行编译后的输出
```
## 许可证
请参阅 [LICENSE](LICENSE)。
