Content
# mcp-freeipa
MCP server for [FreeIPA](https://www.freeipa.org/) / [Red Hat IdM](https://www.redhat.com/en/technologies/management/identity-manager) — user, group, host, DNS, HBAC, and sudo management via the Model Context Protocol.
## Features
- **Users** — list, get, create, enable, disable, delete, and reset passwords
- **Groups** — list, get, and manage group memberships
- **Hosts** — list and inspect enrolled hosts
- **DNS** — list zones, list and get records (A, AAAA, CNAME, MX, PTR, TXT, SRV, …)
- **Sudo rules** — list and inspect sudo policy rules
- **HBAC rules** — list and inspect host-based access control rules
## Requirements
- FreeIPA 4.6+ or Red Hat IdM 7.6+ (any modern version with the JSON-RPC API)
- Node.js 18+
- An admin account or a dedicated service account with read access to the relevant objects
### FreeIPA permissions
The minimum required privileges depend on which tools you use:
| Area | Required privilege |
|---|---|
| Users | `User Administrators` role or `System: Read Users` permission |
| Groups | `Group Administrators` role or `System: Read Groups` permission |
| Hosts | `Host Administrators` role or `System: Read Hosts` permission |
| DNS | `DNS Administrators` role or `System: Read DNS Entries` permission |
| Sudo | `Sudo Administrator` role or `System: Read Sudo Rules` permission |
| HBAC | `HBAC Administrator` role or `System: Read HBAC Rules` permission |
For read-only usage, you can create a dedicated service account and grant it only the `System: Read *` permissions via an RBAC role.
## Environment variables
| Variable | Required | Default | Description |
|---|---|---|---|
| `FREEIPA_HOST` | Yes | — | FreeIPA server hostname (e.g. `ipa.example.com`) |
| `FREEIPA_PASSWORD` | Yes | — | Password for the FreeIPA account |
| `FREEIPA_USERNAME` | No | `admin` | FreeIPA account username |
| `FREEIPA_ALLOW_SELF_SIGNED` | No | `true` | Allow self-signed TLS certificates (`true`/`false`) |
## Installation
```bash
npm install
npm run build
```
## Claude Desktop configuration
Add to `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"
}
}
}
}
```
If you have installed the package globally via `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"
}
}
}
}
```
## Available tools
### Users
| Tool | Description |
|---|---|
| `list_users` | List users, with optional uid / cn / mail filters |
| `get_user` | Get full details for a user by UID |
| `enable_user` | Enable a disabled user account |
| `disable_user` | Disable (lock) a user account |
| `add_user` | Create a new user account |
| `delete_user` | Permanently delete a user account |
| `reset_password` | Reset a user's password |
### Groups
| Tool | Description |
|---|---|
| `list_groups` | List groups with optional name filter |
| `get_group` | Get full details for a group by name |
| `add_user_to_group` | Add one or more users to a group |
| `remove_user_from_group` | Remove one or more users from a group |
### Hosts
| Tool | Description |
|---|---|
| `list_hosts` | List enrolled hosts with optional FQDN filter |
| `get_host` | Get full details for a host by FQDN |
### DNS
| Tool | Description |
|---|---|
| `list_dns_zones` | List all DNS zones |
| `list_dns_records` | List all records in a DNS zone |
| `get_dns_record` | Get all record types for a specific name in a zone |
### Sudo
| Tool | Description |
|---|---|
| `list_sudo_rules` | List all sudo rules |
| `get_sudo_rule` | Get full details of a sudo rule |
### HBAC
| Tool | Description |
|---|---|
| `list_hbac_rules` | List all host-based access control rules |
| `get_hbac_rule` | Get full details of an HBAC rule |
## FreeIPA API notes
The server uses the FreeIPA JSON-RPC API (`/ipa/session/json`). It authenticates with a username and password via form-encoded login (`/ipa/session/login_password`) and stores the resulting `ipa_session` cookie for all subsequent requests. The session cookie is refreshed automatically on expiry (HTTP 401).
FreeIPA returns all attribute values as arrays even for scalar fields (e.g., `{"uid": ["john"]}`). The server normalises these automatically, extracting the first element for scalar fields and preserving full arrays for list fields such as `memberof_group`.
## Development
```bash
npm run dev # run with tsx (no build step)
npm run build # compile TypeScript to dist/
npm start # run compiled output
```
## License
See [LICENSE](LICENSE).
