mcp-freeipa

MCP server for FreeIPA / Red Hat IdM — user, group, host, DNS, HBAC, and sudo management via the Model Context Protocol.

Features

• Users — list, get, create, enable, disable, delete, and reset passwords
• Groups — list, get, and manage group memberships
• Hosts — list and inspect enrolled hosts
• DNS — list zones, list and get records (A, AAAA, CNAME, MX, PTR, TXT, SRV, …)
• Sudo rules — list and inspect sudo policy rules
• HBAC rules — list and inspect host-based access control rules

Requirements

• FreeIPA 4.6+ or Red Hat IdM 7.6+ (any modern version with the JSON-RPC API)
• Node.js 18+
• An admin account or a dedicated service account with read access to the relevant objects

FreeIPA permissions

The minimum required privileges depend on which tools you use:

Area	Required privilege
Users	User Administrators role or System: Read Users permission
Groups	Group Administrators role or System: Read Groups permission
Hosts	Host Administrators role or System: Read Hosts permission
DNS	DNS Administrators role or System: Read DNS Entries permission
Sudo	Sudo Administrator role or System: Read Sudo Rules permission
HBAC	HBAC Administrator role or System: Read HBAC Rules permission

For read-only usage, you can create a dedicated service account and grant it only the System: Read * permissions via an RBAC role.

Environment variables

Variable	Required	Default	Description
FREEIPA_HOST	Yes	—	FreeIPA server hostname (e.g. ipa.example.com)
FREEIPA_PASSWORD	Yes	—	Password for the FreeIPA account
FREEIPA_USERNAME	No	admin	FreeIPA account username
FREEIPA_ALLOW_SELF_SIGNED	No	true	Allow self-signed TLS certificates (true/false)

Installation

npm install
npm run build

Claude Desktop configuration

Add to claude_desktop_config.json:

{
  "mcpServers": {
    "freeipa": {
      "command": "node",
      "args": ["/absolute/path/to/mcp-freeipa/dist/index.js"],
      "env": {
        "FREEIPA_HOST": "ipa.example.com",
        "FREEIPA_USERNAME": "admin",
        "FREEIPA_PASSWORD": "your-password-here",
        "FREEIPA_ALLOW_SELF_SIGNED": "true"
      }
    }
  }
}

If you have installed the package globally via npm install -g mcp-freeipa:

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

Available tools

Users

Tool	Description
list_users	List users, with optional uid / cn / mail filters
get_user	Get full details for a user by UID
enable_user	Enable a disabled user account
disable_user	Disable (lock) a user account
add_user	Create a new user account
delete_user	Permanently delete a user account
reset_password	Reset a user's password

Groups

Tool	Description
list_groups	List groups with optional name filter
get_group	Get full details for a group by name
add_user_to_group	Add one or more users to a group
remove_user_from_group	Remove one or more users from a group

Hosts

Tool	Description
list_hosts	List enrolled hosts with optional FQDN filter
get_host	Get full details for a host by FQDN

DNS

Tool	Description
list_dns_zones	List all DNS zones
list_dns_records	List all records in a DNS zone
get_dns_record	Get all record types for a specific name in a zone

Sudo

Tool	Description
list_sudo_rules	List all sudo rules
get_sudo_rule	Get full details of a sudo rule

HBAC

Tool	Description
list_hbac_rules	List all host-based access control rules
get_hbac_rule	Get full details of an HBAC rule

FreeIPA API notes

The server uses the FreeIPA JSON-RPC API (/ipa/session/json). It authenticates with a username and password via form-encoded login (/ipa/session/login_password) and stores the resulting ipa_session cookie for all subsequent requests. The session cookie is refreshed automatically on expiry (HTTP 401).

FreeIPA returns all attribute values as arrays even for scalar fields (e.g., {"uid": ["john"]}). The server normalises these automatically, extracting the first element for scalar fields and preserving full arrays for list fields such as memberof_group.

Development

npm run dev      # run with tsx (no build step)
npm run build    # compile TypeScript to dist/
npm start        # run compiled output

License

See LICENSE.