bibliocommons-mcp-keycloak 1.0.0

MCP server for Keycloak Identity and Access Management

Keycloak MCP Server

MCP server for Keycloak Identity and Access Management instances. Auto-generates 401 tools from the Keycloak OpenAPI specification using FastMCP.from_openapi(). Includes CodeMode for efficient AI interaction with large tool sets, and supports dual authentication modes (OAuth2 HTTP transport for user sessions, client_credentials for stdio service accounts).

Configuration

Authentication: Keycloak supports two modes depending on transport:

• stdio (service account): Uses client_credentials or password grant to obtain tokens automatically
• HTTP (user OAuth): Uses OIDC proxy to authenticate end-users via browser flow

Option 1: config.json

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

Option 2: Environment Variables

export KEYCLOAK_HOST="keycloak.example.com"
export KEYCLOAK_REALM="master"
export KEYCLOAK_CLIENT_ID="admin-cli"
export KEYCLOAK_CLIENT_SECRET="your-client-secret"
# Or use password grant:
export KEYCLOAK_USERNAME="admin"
export KEYCLOAK_PASSWORD="admin-password"
export KEYCLOAK_VERIFY_SSL="true"
export KEYCLOAK_CA_CERT_PATH=""
export KEYCLOAK_TIMEOUT="30"

Authentication Modes

stdio Mode (Service Account)

For AI assistants connecting via stdio transport. The server acquires tokens automatically using either:

• Client credentials grant: Set client_id + client_secret. Best for service-to-service.
• Password grant: Set username + password. Falls back to admin-cli as client_id.

Tokens are cached and refreshed automatically before expiry.

HTTP Mode (User OAuth Flow)

For web-based access where end-users authenticate via browser:

python -m bibliocommons_mcp_keycloak --transport http --port 8000

Uses OIDC proxy with your Keycloak realm's well-known configuration. Users authenticate through the standard Keycloak login page.

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

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

Claude Desktop

Configuration file:

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

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

VS Code (with MCP Extension)

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

GitHub Copilot (VS Code)

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

Cline (VS Code Extension)

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

Zed Editor

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

Cursor IDE

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

Kiro IDE

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

Kiro CLI

Create or edit ~/.kiro/settings/mcp.json:

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

Configuration Notes

• Replace /absolute/path/to/keycloak/ with the actual path to your server directory
• Add --config /path/to/config.json to the args array to use a specific config file
• Add --read-only to the args array to disable destructive tools
• After adding the configuration, restart your AI client for changes to take effect

Standalone MCP Server

python -m bibliocommons_mcp_keycloak

Read-Only Mode

Disable all write operations (POST, PUT, DELETE, PATCH) for safe, audit-only operation:

# CLI flag
python -m bibliocommons_mcp_keycloak --read-only

# Environment variable
export KEYCLOAK_READ_ONLY=true

In read-only mode, only GET-based tools are exposed. All mutating operations are excluded.

OpenAPI Spec Caching

The server downloads the Keycloak OpenAPI spec on first run and caches it locally as openapi.json. To use a custom cache location:

export KEYCLOAK_SPEC_CACHE="/path/to/openapi.json"

To refresh the cache, delete the file and restart the server.

Security Notes

• Create a dedicated service account in Keycloak for MCP access with minimal required roles
• Never commit config.json with real credentials (excluded by .gitignore)
• Use config.json.example as a template
• Prefer environment variables for production and CI environments
• Use --read-only mode when write access is not needed
• Tokens are cached in memory only and never written to disk
• Set verify_ssl=true in production; only disable for development with self-signed certificates