Keycloak MCP Server for Agentic Data Management

Overview

The Keycloak MCP Server is a lightweight service that exposes Keycloak data as a Model Context Protocol (MCP) provider. It indexes and surfaces Keycloak objects—users, clients, roles, groups, and realm metadata—so downstream agents and LLM-driven workflows can efficiently search and retrieve contextual identity information. By translating Keycloak state into a searchable, structured context endpoint, the server enables automated tooling to make real-time decisions that depend on identity and access data.

This server is particularly useful for teams integrating LLMs or agentic systems with identity management: instead of embedding Keycloak queries directly into agents, you point agents at the MCP endpoint. Agents can request concise, relevant slices of Keycloak data (for example, user attributes, client scope details, or role hierarchies) without direct Keycloak integration, simplifying security boundaries and caching strategies.

Features

• Exposes Keycloak entities (users, clients, roles, groups, realms) via an MCP-compatible API
• Full-text and structured search across Keycloak objects
• Incremental or scheduled indexing from a Keycloak instance
• Authentication to Keycloak using admin credentials or tokens
• Lightweight HTTP server easily containerizable
• Simple JSON-based configuration for realms and index rules
• Health and readiness endpoints for orchestration

Installation / Configuration

Prerequisites:

• Running Keycloak instance (vX or later)
• Docker (recommended) or Node.js runtime (if building locally)

Clone the repo and run with Docker:

git clone https://github.com/idoyudha/mcp-keycloak.git
cd mcp-keycloak

# Build and run with Docker (example)
docker build -t mcp-keycloak .
docker run -e KEYCLOAK_URL="https://keycloak.example.com" \
           -e KEYCLOAK_ADMIN_USER="admin" \
           -e KEYCLOAK_ADMIN_PASSWORD="password" \
           -p 8080:8080 \
           mcp-keycloak

Or run from source (Node.js example):

# Install dependencies
npm install

# Run with env vars
KEYCLOAK_URL="https://keycloak.example.com" \
KEYCLOAK_ADMIN_USER="admin" \
KEYCLOAK_ADMIN_PASSWORD="password" \
npm start

Common environment variables

Example JSON configuration (mcp-config.json):

{
  "realms": ["master", "my-realm"],
  "indexRules": {
    "users": { "fields": ["username", "email", "attributes"] },
    "clients": { "fields": ["clientId", "description"] },
    "roles": { "fields": ["name", "description"] }
  },
  "indexIntervalSeconds": 300
}

Place the file in the container or pass its path via MCP_CONFIG_PATH env var.

Available Resources

• GitHub repository: https://github.com/idoyudha/mcp-keycloak — source, issues, and examples
• Health endpoint: GET /health — basic service liveness
• Readiness endpoint: GET /ready — indexing readiness and Keycloak connectivity
• MCP manifest (if implemented): GET /.well-known/mcp — discovery document for agents
• Main MCP search endpoint: POST /mcp/search — accepts MCP search payloads and returns contextual results

API quick reference

• GET /health — 200 OK when service is up
• GET /ready — 200 when the service has a recent index and can serve requests
• POST /mcp/search — body: MCP search query (filters, text query); returns array of context snippets
• POST /mcp/index — trigger a manual re-index (requires admin access)

Use Cases

• Agentic user-support bot: A conversational agent needs to describe a user’s assigned roles, attributes, and client memberships to help troubleshoot access issues. The bot issues a focused MCP search for a username and receives a concise context payload instead of crawling Keycloak APIs directly.
• Automated access remediation: A workflow monitors anomalous events and needs to remove a compromised client. It queries the MCP server for the client’s details, evaluates policies, then takes action using Keycloak admin APIs—keeping policy evaluation decoupled from Keycloak logic.
• Compliance reporting and audit: Periodic agents generate reports that require a snapshot of roles and group memberships across realms. The MCP server delivers structured search results suitable for aggregation and templated report generation.
• Onboarding assistant: An onboarding agent queries relevant client and role templates for a new service account, then presents curated configuration options to an operator or auto-applies them.

Example: Search request and response

Sample search request (curl):

curl -X POST http://localhost:8080/mcp/search \
  -H "Content-Type: application/json" \
  -d '{
    "query": "username:alice OR email:[email protected]",
    "types": ["user"],
    "limit": 5
  }'

Sample response (JSON):

{
  "results": [
    {
      "type": "user",
      "id": "1234-uuid",
      "snippet": "username: alice, email: [email protected], roles: [developer, api-consumer]",
      "metadata": {
        "realm": "my-realm",
        "lastUpdated": "2026-01-10T12:34:56Z"
      }
    }
  ]
}

Notes

• The MCP server is intended to be used as a read-only, searchable context layer. Administrative actions on Keycloak should still be performed using Keycloak’s APIs with appropriate authentication.
• Tune indexing frequency and fields to balance freshness with load on your Keycloak instance.

For implementation details, examples, and contribution guidelines, see the project repository: https://github.com/idoyudha/mcp-keycloak.