FreeIPA MCP Server

MCP server for FreeIPA identity management instances. Tools are dynamically registered from FreeIPA's schema API, exposing ~290 commands covering users, groups, hosts, DNS, HBAC, sudo rules, certificates, services, trusts, vaults, and more.

The server uses CodeMode for efficient LLM interaction, collapsing ~290 individual tools into 3 meta-tools (get_tags, search, get_schemas) that let AI assistants discover and call commands on demand rather than loading all tools into context at once.

Both MCP (stdio) and REST API (Swagger UI) interfaces are available, sharing the same underlying FreeIPA client.

Configuration

Authentication: FreeIPA supports two authentication methods:

• Password — username/password with session cookies (simpler, good for development)
• Kerberos — keytab-based authentication (recommended for production, no passwords stored)

Option 1: config.json (Password Auth)

cp config.json.example config.json
# Edit config.json with your credentials

{
  "host": "ipa.example.com",
  "auth_method": "password",
  "username": "api-user",
  "password": "changeme",
  "verify_ssl": true,
  "ca_cert_path": "/etc/ipa/ca.crt"
}

Option 1b: config.json (Kerberos Auth)

{
  "host": "ipa.example.com",
  "auth_method": "kerberos",
  "principal": "mcp-api",
  "keytab_path": "/root/mcp-api.keytab",
  "verify_ssl": true,
  "ca_cert_path": "/etc/ipa/ipa-ca.cert"
}

The server runs kinit -kt <keytab_path> <principal> automatically. No password needed.

Option 2: Environment Variables

# Password auth
export FREEIPA_HOST="ipa.example.com"
export FREEIPA_AUTH_METHOD="password"
export FREEIPA_USERNAME="api-user"
export FREEIPA_PASSWORD="api-password"
export FREEIPA_VERIFY_SSL="true"
export FREEIPA_CA_CERT_PATH="/etc/ipa/ca.crt"

# Or Kerberos auth
export FREEIPA_HOST="ipa.example.com"
export FREEIPA_AUTH_METHOD="kerberos"
export FREEIPA_PRINCIPAL="mcp-api"
export FREEIPA_KEYTAB_PATH="/root/mcp-api.keytab"
export FREEIPA_VERIFY_SSL="true"
export FREEIPA_CA_CERT_PATH="/etc/ipa/ipa-ca.cert"

CA Certificate Setup

FreeIPA servers typically use a self-signed CA. To connect with SSL verification enabled:

1. Copy the IPA CA certificate from the FreeIPA server:

   scp root@ipa.example.com:/etc/ipa/ca.crt /usr/local/share/ca-certificates/ipa-ca.crt
   

2. Set ca_cert_path in config.json or FREEIPA_CA_CERT_PATH to the local path.

Alternatively, set verify_ssl to false for development environments (not recommended for production).

Installation

Option 1: Using uvx (Recommended — no install needed)

uvx bibliocommons-mcp-freeipa

uvx runs the package directly from PyPI in an isolated environment. Install uv first if you don't have it:

curl -LsSf https://astral.sh/uv/install.sh | sh

Option 2: Using pip

pip install bibliocommons-mcp-freeipa

Development

pip install -e ".[dev]"

For local development with an MCP client:

"args": ["--from", "/path/to/freeipa", "bibliocommons-mcp-freeipa"]

AI Client Setup

VS Code (with MCP Extension)

1. Install an MCP-compatible extension in VS Code
2. Open VS Code Settings (JSON): Cmd+Shift+P → "Preferences: Open User Settings (JSON)"
3. Add the server configuration:

{
  "mcp.servers": {
    "freeipa": {
      "command": "uvx",
      "args": ["bibliocommons-mcp-freeipa"]
    }
  }
}

Alternative: Using python directly

{
  "mcp.servers": {
    "freeipa": {
      "command": "python",
      "args": ["-m", "bibliocommons_mcp_freeipa"]
    }
  }
}

Claude Desktop

1. Open Claude Desktop configuration:

   • macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
   • Windows: %APPDATA%\Claude\claude_desktop_config.json

2. Add the server configuration:

{
  "mcpServers": {
    "freeipa": {
      "command": "uvx",
      "args": ["bibliocommons-mcp-freeipa"]
    }
  }
}

Alternative: Using python directly

{
  "mcpServers": {
    "freeipa": {
      "command": "python",
      "args": ["-m", "bibliocommons_mcp_freeipa"]
    }
  }
}

Kiro IDE

1. Open Kiro IDE settings
2. Navigate to MCP Servers configuration
3. Add the server:

{
  "mcpServers": {
    "freeipa": {
      "command": "uvx",
      "args": ["bibliocommons-mcp-freeipa"]
    }
  }
}

Alternative: Using python directly

{
  "mcpServers": {
    "freeipa": {
      "command": "python",
      "args": ["-m", "bibliocommons_mcp_freeipa"]
    }
  }
}

Kiro CLI

1. Create or edit the MCP configuration file:

   • User level: ~/.kiro/settings/mcp.json
   • Project level: <project-root>/.kiro/settings/mcp.json

2. Add the server configuration:

{
  "mcpServers": {
    "freeipa": {
      "command": "uvx",
      "args": ["bibliocommons-mcp-freeipa"]
    }
  }
}

Alternative: Using python directly

{
  "mcpServers": {
    "freeipa": {
      "command": "python",
      "args": ["-m", "bibliocommons_mcp_freeipa"]
    }
  }
}

Configuration Notes

• Using uvx (default): Automatically manages dependencies in isolated environments (like npx for Node.js)
• Using python (alternative): Requires pip install bibliocommons-mcp-freeipa first
• After adding the configuration, restart your AI client for changes to take effect

For other AI clients (Amazon Q, GitHub Copilot, Cline, Zed, Cursor), see docs/ai-clients.md.

Docker

# Pull from Docker Hub (private)
docker pull bibliocommons/mcp-freeipa:latest

# Run in stdio mode
docker run -i --rm \
  -v /path/to/config.json:/config.json:ro \
  bibliocommons/mcp-freeipa:latest \
  --config /config.json

# Run in HTTP mode
docker run -d --rm \
  -v /path/to/config.json:/config.json:ro \
  -p 8000:8000 \
  bibliocommons/mcp-freeipa:latest \
  --config /config.json --transport http --port 8000

# Run in expanded mode
docker run -i --rm \
  -v /path/to/config.json:/config.json:ro \
  bibliocommons/mcp-freeipa:latest \
  --config /config.json --expanded

Web UI with Swagger

A REST API with interactive Swagger documentation is available:

python -m bibliocommons_mcp_freeipa.webui

Access the Swagger UI at: http://localhost:8000/docs

The Web UI provides:

• Interactive API documentation
• Try-it-out functionality for all endpoints
• OpenAPI/Swagger specification
• REST API access to all FreeIPA commands

Standalone MCP Server

python -m bibliocommons_mcp_freeipa

CLI Flags

Flag	Env Var	Description
--config PATH	FREEIPA_CONFIG	Path to config.json
--read-only	FREEIPA_READ_ONLY	Exclude destructive tools
--expanded	FREEIPA_EXPANDED	Register all tools individually instead of gateway mode
--transport stdio|http	FREEIPA_TRANSPORT	Transport mode (default: stdio)
--port PORT	FREEIPA_PORT	HTTP port (default: 8000)
--version	—	Show version and exit

Gateway Mode (Default)

By default, the server exposes 2 tools instead of ~290 individual tools:

Tool	Purpose
freeipa_api	Execute any FreeIPA action by name with a params dict
freeipa_help	Search available actions, parameters, and descriptions

The AI assistant calls freeipa_help to discover available actions, then calls freeipa_api(action="user_find", params={"uid": "jdoe"}) to execute them.

To register all individual tools, use --expanded:

python -m bibliocommons_mcp_freeipa --expanded

Tool Domains

Tools are dynamically registered from the FreeIPA schema. The exact count depends on your FreeIPA version and installed plugins. Typical domains include:

Domain	Prefix	Approx. Commands	Examples
Users	user_	~19	user_add, user_find, user_mod, user_show
Groups	group_	~9	group_add, group_find, group_add_member
Hosts	host_	~22	host_add, host_find, host_show
DNS	dns	~28	dnszone_add, dnsrecord_add, dnsrecord_find
HBAC	hbac	~20	hbacrule_add, hbacrule_add_user, hbactest
Sudo	sudo	~25	sudorule_add, sudorule_add_user, sudocmd_add
Certificates	cert_	~17	cert_request, cert_show, cert_revoke
Services	service_	~22	service_add, service_find, service_show
Trusts	trust_	~16	trust_add, trust_find, trust_show
Vaults	vault_	~16	vault_add, vault_archive, vault_retrieve
Password Policy	pwpolicy_	~5	pwpolicy_add, pwpolicy_mod, pwpolicy_show
Kerberos	krbtpolicy_	~3	krbtpolicy_mod, krbtpolicy_show
SELinux	selinux	~5	selinuxusermap_add, selinuxusermap_find
Automount	automount	~15	automountlocation_add, automountmap_add
Other	various	~70+	config_mod, ping, whoami, batch

Schema Caching

On startup, the server fetches the full command schema from FreeIPA's schema API endpoint. This schema defines all available commands, their parameters, types, and documentation.

The schema is cached locally in schema_cache.json. If the live fetch fails (e.g., FreeIPA is temporarily unreachable), the server falls back to the cached version.

To refresh the cache after a FreeIPA upgrade or plugin change:

rm schema_cache.json
# Restart the server - it will fetch and cache the new schema

Security Notes

• Dedicated API user: Create a FreeIPA user specifically for API access with only the permissions needed. Avoid using admin in production.
• CA certificate: Configure ca_cert_path to point to your IPA CA certificate rather than disabling SSL verification.
• Session handling: The client authenticates via password and maintains a session cookie. If the session expires (401), it re-authenticates automatically.
• Never commit config.json: The .gitignore excludes config.json. Use config.json.example as a template and keep credentials out of version control.