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)

Write Tools (10)

CLI

The companion ipa-cli provides the same capabilities via shell commands — use when token budget matters or shell access is available.

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):

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