Content
> **Mirror notice.** This repository is a personal mirror of `vhspace/ipa-mcp` v1.3.0, restored from a locally-cached wheel after the upstream repository was removed from GitHub. The source is preserved as-is under its original Apache-2.0 license.
>
> The `mcp-common` dependency is also mirrored at [puhamihai/mcp-common](https://github.com/puhamihai/mcp-common); the install chain is self-contained.
# IPA MCP Server
[](https://www.python.org/downloads/)
[](https://opensource.org/licenses/Apache-2.0)
MCP server and CLI for [FreeIPA](https://www.freeipa.org/) — manages user groups, host groups, HBAC rules, and sudo rules via the FreeIPA JSON-RPC API. Designed for forge cluster bringup and access control automation in the Together AI SRE stack.
## Quick Start
### Claude Code / Cursor / generic MCP client
Point your MCP config at the git URL — `uvx` will install both this package and the mirrored `mcp-common` automatically:
```json
{
"mcpServers": {
"ipa-mcp": {
"command": "uvx",
"args": ["--from", "git+https://github.com/puhamihai/ipa-mcp", "ipa-mcp"],
"env": {
"IPA_HOST": "ipa.example.com",
"IPA_USERNAME": "admin",
"IPA_PASSWORD": "your-password"
}
}
}
}
```
### From Source
```bash
git clone https://github.com/puhamihai/ipa-mcp
cd ipa-mcp
uv sync
uv run ipa-mcp
```
## Tools
### Read Tools (6)
| Tool | Description |
|------|-------------|
| `ipa_list_groups` | List user groups |
| `ipa_list_hostgroups` | List host groups |
| `ipa_list_hbac_rules` | List HBAC rules |
| `ipa_list_sudo_rules` | List sudo rules |
| `ipa_list_users` | List users |
| `ipa_list_hosts` | List hosts |
### Write Tools (18)
| Tool | Description |
|------|-------------|
| `ipa_create_user` | Create user (optional random or explicit password, SSH keys) |
| `ipa_modify_user` | Modify user attributes / SSH keys / reset random password |
| `ipa_enable_user` | Enable (unlock) user account |
| `ipa_disable_user` | Disable (lock) user account |
| `ipa_delete_user` | Delete user (hard or `preserve=True` soft-delete) |
| `ipa_set_user_password` | Admin password reset (expires on first login) |
| `ipa_create_group` | Create user group |
| `ipa_add_group_members` | Add users to group |
| `ipa_remove_group_members` | Remove users from group |
| `ipa_create_hostgroup` | Create host group |
| `ipa_add_hostgroup_members` | Add hosts to host group |
| `ipa_remove_hostgroup_members` | Remove hosts from host group |
| `ipa_create_hbac_rule` | Create HBAC rule |
| `ipa_add_hbac_rule_members` | Add members to HBAC rule |
| `ipa_create_sudo_rule` | Create sudo rule |
| `ipa_add_sudo_rule_members` | Add members to sudo rule |
| `ipa_add_sudo_option` | Add sudo option |
| `ipa_setup_forge` | One-shot forge cluster setup (groups + HBAC + sudo) |
## CLI
The companion `ipa-cli` provides the same capabilities via shell commands.
| Task | Command |
|------|---------|
| List user groups | `ipa-cli groups` |
| List host groups | `ipa-cli hostgroups` |
| List HBAC rules | `ipa-cli hbac-rules` |
| List sudo rules | `ipa-cli sudo-rules` |
| List users | `ipa-cli users` |
| List hosts | `ipa-cli hosts` |
| Create user group | `ipa-cli create-group <name> --desc "description"` |
| Create host group | `ipa-cli create-hostgroup <name>` |
| Full forge setup | `ipa-cli setup-forge <cluster> --hosts "host1,host2" --users "alice,bob"` |
## Configuration
### Environment Variables
| Variable | Required | Default | Description |
|----------|----------|---------|-------------|
| `IPA_HOST` | Yes | — | FreeIPA server hostname or URL |
| `IPA_USERNAME` | No | `admin` | IPA API username |
| `IPA_PASSWORD` | Yes | — | IPA admin password |
| `IPA_VERIFY_SSL` | No | `false` | SSL certificate verification |
Aliases: `IPA_URL` for `IPA_HOST`, `IPA_USER` for `IPA_USERNAME`, `IPA_PASS` for `IPA_PASSWORD`.
## License
Apache License 2.0
