Metadata-Version: 2.4
Name: bibliocommons-mcp-freeipa
Version: 1.0.0
Summary: MCP server for FreeIPA identity management
Author-email: Cody Lusk <cody.lusk@bibliocommons.com>
License: MIT
Requires-Python: >=3.10
Description-Content-Type: text/markdown
Requires-Dist: fastmcp[code-mode]>=3.2.4
Requires-Dist: requests>=2.33.1
Requires-Dist: fastapi>=0.136.1
Requires-Dist: uvicorn>=0.46.0
Provides-Extra: kerberos
Requires-Dist: requests-gssapi>=1.4.0; extra == "kerberos"
Provides-Extra: dev
Requires-Dist: pytest>=9.0.3; extra == "dev"
Requires-Dist: pytest-asyncio>=1.3.0; extra == "dev"
Requires-Dist: pytest-cov>=7.1.0; extra == "dev"
Requires-Dist: httpx>=0.28.1; extra == "dev"

# 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](https://gofastmcp.com/servers/transforms/code-mode#code-mode) 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

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

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

### Option 2: Environment Variables

```bash
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:
   ```bash
   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 uv (Recommended)

[uv](https://github.com/astral-sh/uv) is a fast Python package manager. Install it first:

```bash
# 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

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

## AI Client Setup

**Quick Links**: [Amazon Q](#amazon-q-developer-vs-code) | [Claude Desktop](#claude-desktop) | [VS Code](#vs-code-with-mcp-extension) | [GitHub Copilot](#github-copilot-vs-code) | [Cline](#cline-vs-code-extension) | [Zed](#zed-editor) | [Cursor](#cursor-ide) | [Kiro IDE](#kiro-ide) | [Kiro CLI](#kiro-cli)

### Amazon Q Developer (VS Code)

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

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


**Alternative: Using python directly**

```json
{
  "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:

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


**Alternative: Using python directly**

```json
{
  "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:

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


**Alternative: Using python directly**

```json
{
  "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:

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


**Alternative: Using python directly**

```json
{
  "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:

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


**Alternative: Using python directly**

```json
{
  "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:

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


**Alternative: Using python directly**

```json
{
  "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:

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


**Alternative: Using python directly**

```json
{
  "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:

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


**Alternative: Using python directly**

```json
{
  "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:

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


**Alternative: Using python directly**

```json
{
  "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:

```bash
python -m bibliocommons_mcp_freeipa.webui
```

Access the Swagger UI at: [http://localhost:8000/docs](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

```bash
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:

```bash
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.
