bibliocommons-mcp-freeipa 1.0.0

MCP server for FreeIPA identity management

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 uses password-based authentication with session cookies. It's recommended to create a dedicated API user account in FreeIPA rather than using a personal account.

Option 1: config.json

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

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

Option 2: Environment Variables

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

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 [e-mail]:/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 uv (Recommended)

uv is a fast Python package manager. Install it first:

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

# Windows
powershell -c "irm https://astral.sh/uv/install.ps1 | iex"

No additional installation needed - uvx will handle dependencies automatically.

Option 2: Using pip

pip install bibliocommons-mcp-freeipa
# or for development
pip install -e ".[dev]"

AI Client Setup

Quick Links: Amazon Q | Claude Desktop | VS Code | GitHub Copilot | Cline | Zed | Cursor | Kiro IDE | Kiro CLI

Amazon Q Developer (VS Code)

1. Install the Amazon Q extension in VS Code
2. Open VS Code Settings (JSON) and add:

{
  "amazonQ.mcp.servers": {
    "freeipa": {
      "command": "uvx",
      "args": ["--from", "/absolute/path/to/freeipa", "bibliocommons-mcp-freeipa"]
    }
  }
}

Alternative: Using python directly

{
  "amazonQ.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": ["--from", "/absolute/path/to/freeipa", "bibliocommons-mcp-freeipa"]
    }
  }
}

Alternative: Using python directly

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

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": ["--from", "/absolute/path/to/freeipa", "bibliocommons-mcp-freeipa"]
    }
  }
}

Alternative: Using python directly

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

GitHub Copilot (VS Code)

1. Install GitHub Copilot extension in VS Code
2. Open VS Code Settings (JSON) and add:

{
  "github.copilot.chat.mcp.servers": {
    "freeipa": {
      "command": "uvx",
      "args": ["--from", "/absolute/path/to/freeipa", "bibliocommons-mcp-freeipa"]
    }
  }
}

Alternative: Using python directly

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

Cline (VS Code Extension)

1. Install the Cline extension in VS Code
2. Open VS Code Settings (JSON) and add:

{
  "cline.mcpServers": {
    "freeipa": {
      "command": "uvx",
      "args": ["--from", "/absolute/path/to/freeipa", "bibliocommons-mcp-freeipa"]
    }
  }
}

Alternative: Using python directly

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

Zed Editor

1. Open Zed settings: Cmd+, (macOS) or Ctrl+, (Linux/Windows)
2. Navigate to "Language Models" → "Configure MCP Servers"
3. Add the server configuration:

{
  "mcpServers": {
    "freeipa": {
      "command": "uvx",
      "args": ["--from", "/absolute/path/to/freeipa", "bibliocommons-mcp-freeipa"]
    }
  }
}

Alternative: Using python directly

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

Cursor IDE

1. Open Cursor Settings (JSON): Cmd+Shift+P → "Preferences: Open User Settings (JSON)"
2. Add the MCP server configuration:

{
  "mcp.servers": {
    "freeipa": {
      "command": "uvx",
      "args": ["--from", "/absolute/path/to/freeipa", "bibliocommons-mcp-freeipa"]
    }
  }
}

Alternative: Using python directly

{
  "mcp.servers": {
    "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": ["--from", "/absolute/path/to/freeipa", "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": ["--from", "/absolute/path/to/freeipa", "bibliocommons-mcp-freeipa"]
    }
  }
}

Alternative: Using python directly

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

Configuration Notes

• Replace /absolute/path/to/freeipa/ with the actual path to your server directory
• 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

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

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.