Metadata-Version: 2.4
Name: bibliocommons-mcp-freeipa
Version: 1.2.2
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
Requires-Dist: python-multipart>=0.0.27
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 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)

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

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

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

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

### 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"]
    }
  }
}
```

### 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"]
    }
  }
}
```

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

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

## Docker

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

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

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

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

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