# 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).