FreeIPA MCP Server

A Model Context Protocol (MCP) server for FreeIPA identity management. Enables AI assistants like Claude to manage users, groups, hosts, DNS, HBAC rules, sudo rules, and certificates through natural language.

Requirements

Python 3.10+
FreeIPA 4.6.5+ (API version 2.230+)
Network access to your FreeIPA server

For more information about FreeIPA concepts (HBAC, sudo rules, etc.), see the FreeIPA Documentation.

Installation

# From source
cd freeipa-mcp
pip install -e .

# Or with uv
uv pip install -e .

Configuration

Set environment variables for your FreeIPA server:

export FREEIPA_SERVER=ipa.example.com
export FREEIPA_USERNAME=admin
export FREEIPA_PASSWORD=your-password

# Optional settings
export FREEIPA_VERIFY_SSL=true        # default: true
export FREEIPA_CA_CERT_PATH=/etc/ipa/ca.crt  # for custom CA certificates
export FREEIPA_API_VERSION=2.230      # default: 2.230
export FREEIPA_DEFAULT_LIMIT=100      # max results for list operations
export FREEIPA_REQUEST_TIMEOUT=30     # request timeout in seconds

Or create a .env file:

cp .env.example .env
# Edit .env with your settings

Usage with Claude Code

Add to your ~/.claude.json:

{
  "mcpServers": {
    "freeipa": {
      "type": "stdio",
      "command": "freeipa-mcp",
      "env": {
        "FREEIPA_SERVER": "ipa.example.com",
        "FREEIPA_USERNAME": "admin",
        "FREEIPA_PASSWORD": "your-password"
      }
    }
  }
}

Security: Avoid committing credentials to version control. Consider using environment variables from your shell profile or a secrets manager instead of hardcoding passwords in configuration files.

Once published to PyPI, you can also use uvx (no local installation needed):

{
  "mcpServers": {
    "freeipa": {
      "type": "stdio",
      "command": "uvx",
      "args": ["freeipa-mcp"],
      "env": {
        "FREEIPA_SERVER": "ipa.example.com",
        "FREEIPA_USERNAME": "admin",
        "FREEIPA_PASSWORD": "your-password"
      }
    }
  }
}

Available Tools

User Management

| Tool | Description | |------|-------------| | user_find | Search users with filters | | user_show | Get user details | | user_add | Create a new user | | user_mod | Modify user attributes | | user_del | Delete a user | | user_enable | Enable user account | | user_disable | Disable user account | | user_unlock | Unlock locked account |

Group Management

| Tool | Description | |------|-------------| | group_find | Search groups | | group_show | Get group details | | group_add | Create a new group | | group_mod | Modify group | | group_del | Delete a group | | group_add_member | Add members to group | | group_remove_member | Remove members |

Host Management

| Tool | Description | |------|-------------| | host_find | Search hosts | | host_show | Get host details | | host_add | Register a new host | | host_mod | Modify host | | host_del | Delete a host | | host_disable | Disable host |

DNS Management

| Tool | Description | |------|-------------| | dnszone_find | List DNS zones | | dnszone_show | Get zone details | | dnszone_add | Create DNS zone | | dnsrecord_find | Search DNS records | | dnsrecord_add | Add DNS record | | dnsrecord_del | Delete DNS record |

HBAC Rules

| Tool | Description | |------|-------------| | hbacrule_find | Search HBAC rules | | hbacrule_show | Get rule details | | hbacrule_add | Create HBAC rule | | hbacrule_enable | Enable rule | | hbacrule_disable | Disable rule | | hbacrule_add_user | Add users to rule | | hbacrule_add_host | Add hosts to rule |

Sudo Rules

| Tool | Description | |------|-------------| | sudorule_find | Search sudo rules | | sudorule_show | Get rule details | | sudorule_add | Create sudo rule | | sudorule_enable | Enable rule | | sudorule_disable | Disable rule | | sudorule_add_user | Add users to rule | | sudorule_add_host | Add hosts to rule | | sudorule_add_allow_command | Add allowed commands | | sudorule_add_option | Add sudo options |

Certificates

| Tool | Description | |------|-------------| | cert_find | Search certificates | | user_add_cert | Add cert to user | | host_add_cert | Add cert to host |

Example Conversations

Create a user:

"Create a new user 'jsmith' with name John Smith and email jsmith@example.com"

Add user to group:

"Add user jsmith to the developers group"

Create an HBAC rule:

"Create an HBAC rule that allows the developers group to access all hosts via SSH"

Search for expiring certificates:

"Find all certificates expiring before 2026-12-31"

Development

# Install dev dependencies
pip install -e ".[dev]"

# Run linting
ruff check src/

# Run type checking
mypy src/

# Run tests
pytest

Testing with MCP Inspector

# Build and test
pip install -e .
npx @modelcontextprotocol/inspector

# In inspector, connect via stdio to: freeipa-mcp

Troubleshooting

SSL Certificate Errors If your FreeIPA server uses a self-signed certificate:

# Option 1: Provide the CA certificate path
export FREEIPA_CA_CERT_PATH=/etc/ipa/ca.crt

# Option 2: Disable SSL verification (not recommended for production)
export FREEIPA_VERIFY_SSL=false

Authentication Failures

Verify your username and password are correct
Ensure the user has sufficient privileges in FreeIPA
Check that the account is not locked or expired

Connection Issues

Verify network connectivity to the FreeIPA server: ping ipa.example.com
Ensure the FreeIPA API is accessible: curl -k https://ipa.example.com/ipa/json
Check firewall rules allow HTTPS (port 443) traffic

Timeout Errors For slow networks or large queries, increase the timeout:

export FREEIPA_REQUEST_TIMEOUT=60

License

MIT

MCP Servers