IPA MCP Server

MCP server and CLI for FreeIPA — 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

Cursor IDE

Add to .cursor/mcp.json:

{
  "mcpServers": {
    "ipa-mcp": {
      "command": "uvx",
      "args": ["--from", "ipa-mcp", "ipa-mcp"],
      "env": {
        "IPA_HOST": "ipa.example.com",
        "IPA_USERNAME": "admin",
        "IPA_PASSWORD": "your-password"
      }
    }
  }
}

From Source

cd ipa-mcp
uv sync --all-groups
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 (10)

Tool	Description
`ipa_create_group`	Create user group
`ipa_add_group_members`	Add users to group
`ipa_create_hostgroup`	Create host group
`ipa_add_hostgroup_members`	Add hosts to 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 — use when token budget matters or shell access is available.

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"`

Install CLI: uvx --from ipa-mcp ipa-cli or run from repo with uv run ipa-cli.

Cross-MCP Integration

This server works alongside other MCP servers in the SRE stack:

NetBox MCP — Look up host FQDNs before adding them to IPA host groups. NetBox is the source of truth for device inventory.
AWX MCP — Trigger Ansible playbooks for IPA enrollment or host provisioning after forge setup.
MAAS MCP — Coordinate with MAAS when commissioning nodes that will be enrolled in IPA.

Installation

Requires Python 3.12+ and a FreeIPA server with JSON-RPC API enabled.

uv add ipa-mcp
# or
pip install ipa-mcp

For development from source:

cd ipa-mcp
uv sync --all-groups

Configuration

Environment Variables

Create a .env file (see env.example):

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 (typically false for self-signed)

Aliases: IPA_URL for IPA_HOST, IPA_USER for IPA_USERNAME, IPA_PASS for IPA_PASSWORD.

Command Line

ipa-mcp                    # stdio (default)
ipa-cli groups             # CLI
ipa-cli setup-forge cartesia5 --hosts "host1.cloud.together.ai" --users "alice"

Cursor / Claude Code Integration

Cursor (`.cursor/mcp.json` or `.mcp.json`)

{
  "mcpServers": {
    "ipa-mcp": {
      "command": "uv",
      "args": ["--directory", "/path/to/ipa-mcp", "run", "ipa-mcp"],
      "env": {
        "IPA_HOST": "ipa.example.com",
        "IPA_USERNAME": "admin",
        "IPA_PASSWORD": "your-password"
      }
    }
  }
}

Claude Code

claude mcp add ipa-mcp -- uv --directory /path/to/ipa-mcp run ipa-mcp

Development

uv sync --all-groups
uv run ruff check src/ tests/
uv run ruff format src/ tests/
uv run pytest -v
uv run mypy src/

Project Structure

src/ipa_mcp/
├── config.py       # Pydantic Settings
├── ipa_client.py   # FreeIPA JSON-RPC client
├── server.py       # FastMCP tools and entrypoint
└── cli.py          # Typer CLI

Security

Credentials are SecretStr and redacted in logs
Never commit .env files with real credentials
FreeIPA servers often use self-signed certs — IPA_VERIFY_SSL=false is typical

License

Apache License 2.0

IPA MCP Server

IPA MCP Server

Quick Start

Cursor IDE

From Source

Tools

Read Tools (6)

Write Tools (10)

CLI

Cross-MCP Integration

Installation

Configuration

Environment Variables

Command Line

Cursor / Claude Code Integration

Cursor (.cursor/mcp.json or .mcp.json)

Claude Code

Development

Project Structure

Security

License

Reviews

Cursor (`.cursor/mcp.json` or `.mcp.json`)