Entry point wrapper for AI tools to integrate with Keycloak via the Model Context Protocol (MCP).

This package serves as a streamlined entry point for AI assistants (like Claude Desktop) to interact with Keycloak. It loads environment configuration and starts the another-keycloak-mcp server automatically.

npm install

Copy the example environment file and configure it:

cp .env.example .env

Edit .env with your Keycloak connection details:

# Keycloak Server Configuration
# IMPORTANT: Use 'localhost' or '127.0.0.1', not '0.0.0.0'
# For legacy Keycloak (<17) use: http://localhost:8082/auth
# For modern Keycloak (>=17) use: http://localhost:8082
KEYCLOAK_URL=http://localhost:8082/auth
KEYCLOAK_REALM=my-realm

# Authentication Method 1 (Recommended): Client Credentials
# Use a dedicated OIDC client with service account enabled
KEYCLOAK_CLIENT_ID=sso-admin-mcp
KEYCLOAK_CLIENT_SECRET=test12345

# Authentication Method 2 (Alternative): Admin User Credentials
# Note: Some Keycloak setups may not allow password grant type
# KEYCLOAK_ADMIN_USERNAME=admin
# KEYCLOAK_ADMIN_PASSWORD=admin

# Operation Mode: development | production
OPERATION_MODE=development

# Read-Only Mode: true | false
READ_ONLY_MODE=false

# Transport: stdio | http
TRANSPORT=stdio

# Logging Level: error | warn | info | debug
LOG_LEVEL=info

npm run build

npm start

Or use the binary directly:

node dist/index.js

This MCP server can be integrated with various AI tools that support the Model Context Protocol.

Create or edit .cursor/mcp.json in your project directory:

{
  "mcpServers": {
    "keycloak": {
      "command": "node",
      "args": [
        "/absolute/path/to/keycloak-mcp-entrypoint/dist/index.js"
      ]
    }
  }
}

Important: Replace the path with your actual absolute path.

After configuration:

1. Save the mcp.json file
2. Restart Cursor completely
3. The Keycloak tools should appear in Cursor's AI context
4. You can now ask Cursor to perform Keycloak operations (e.g., "list all users in the acme-x realm")

Add the following configuration to your Claude Desktop config file.

Configuration File Locations:

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

Edit ~/Library/Application Support/Claude/claude_desktop_config.json:

{
  "mcpServers": {
    "keycloak": {
      "command": "node",
      "args": [
        "/absolute/path/to/keycloak-mcp-entrypoint/dist/index.js"
      ]
    }
  }
}

Important: Replace the path with your actual absolute path. To get your current directory path, run:

cd /path/to/keycloak-mcp-entrypoint
pwd

Edit %APPDATA%\Claude\claude_desktop_config.json:

{
  "mcpServers": {
    "keycloak": {
      "command": "node",
      "args": [
        "C:\\Users\\YourUsername\\Documents\\keycloak-mcp-entrypoint\\dist\\index.js"
      ]
    }
  }
}

1. Save the config file
2. Completely quit and restart Claude Desktop (not just reload)
3. Open a new conversation
4. Look for the Keycloak MCP tools in the tools panel (hammer icon)
5. You should see all 45 Keycloak management tools available

The KEYCLOAK_URL format depends on your Keycloak version:

• Legacy Keycloak (< 17) or Red Hat SSO: Use http://localhost:8082/auth
• Modern Keycloak (>= 17): Use http://localhost:8082

Important: Always use localhost or 127.0.0.1 for the client URL, not 0.0.0.0. While 0.0.0.0 is valid for server binding, it's not a valid target for HTTP clients.

The MCP server supports two authentication methods:

This is the recommended approach for service-to-service authentication. The MCP server will use OIDC client credentials flow.

Requirements:

1. Create a dedicated OIDC client in Keycloak (e.g., sso-admin-mcp)
2. Enable "Service Accounts" for the client
3. Assign appropriate roles to the service account:
   • Go to the client → Service Account Roles tab
   • Assign realm-management roles (e.g., view-users, manage-users, view-realm, etc.)

Configuration:

KEYCLOAK_CLIENT_ID=sso-admin-mcp
KEYCLOAK_CLIENT_SECRET=test12345

Advantages:

• More secure than username/password
• Works when password grant type is disabled
• Better for service accounts
• Supports token refresh

Uses admin username and password with the password grant type. This may not work if your Keycloak configuration disables the password grant type for security reasons.

Configuration:

KEYCLOAK_ADMIN_USERNAME=admin
KEYCLOAK_ADMIN_PASSWORD=admin
# Leave CLIENT_SECRET empty to use this method

Note: If both client credentials and username/password are provided, client credentials will be used (prioritized).

This entry point provides access to all 45 tools from another-keycloak-mcp:

• User Management (13 tools): Create, read, update, delete users, manage attributes, check multiple accounts, verify IDP links
• Group Management (16 tools): Full CRUD, hierarchy management, attribute search, boolean toggles
• Realm Operations (3 tools): List, read, and get stats for realms
• Authentication (3 tools): Manage authentication flows and required actions
• Realm Tools (3 tools): Export realms, check SAML certificates, list custom SPIs
• Client Scopes (7 tools): Full CRUD for client scope management

• Operation Modes: Run in development or production mode with different safety levels
• Read-Only Mode: Prevent all write operations when enabled
• Safety Checks: All destructive operations include safety warnings and checks
• Validation: All inputs validated with Zod schemas
• Automatic Token Refresh: Keycloak access tokens are automatically refreshed before expiration to prevent authentication failures

• npm run build - Build the project
• npm run dev - Build in watch mode
• npm start - Run the built entry point
• npm run clean - Clean the dist folder
• npm run type-check - Run TypeScript type checking

keycloak-mcp-entrypoint/
├── src/
│   └── index.ts          # Entry point script
├── dist/                 # Built output
├── .env                  # Your configuration (not committed)
├── .env.example          # Example configuration
├── package.json          # Project dependencies
├── tsconfig.json         # TypeScript configuration
└── tsup.config.ts        # Build configuration

If you cannot connect to Keycloak:

1. Verify Keycloak is running:

   curl http://localhost:8082/auth/realms/master/.well-known/openid-configuration

   You should see a JSON response with Keycloak configuration.

2. Check your .env file has the correct KEYCLOAK_URL:

   • Use localhost or 127.0.0.1, NOT 0.0.0.0
   • For legacy Keycloak (<17): http://localhost:8082/auth
   • For modern Keycloak (>=17): http://localhost:8082

3. Verify admin credentials are correct:

   • Check your Keycloak admin console credentials
   • Default is typically admin / admin for local development

4. Check logs for detailed error messages:

   npm start

   Look for connection errors or authentication failures in the output.

5. Common Error: "Unable to determine error message"

   • This usually means the URL is incorrect (likely using 0.0.0.0 instead of localhost)
   • Or the /auth path is missing for legacy Keycloak versions

6. 401 Unauthorized Error:

   • The MCP server automatically refreshes expired tokens, but if you still see 401 errors:
   • Verify credentials in .env are correct
   • Check that the service account has proper roles assigned in Keycloak
   • Ensure the realm name is spelled correctly
   • Try restarting the MCP server (restart Cursor or Claude Desktop)

7. "unauthorized_client" Error:

   • This means the client doesn't support the authentication method being used
   • Solution: Switch to client credentials authentication (Method 1)
   • Ensure your Keycloak client has "Service Accounts Enabled" turned ON
   • Assign proper realm-management roles to the service account
   • Update your .env to use KEYCLOAK_CLIENT_ID and KEYCLOAK_CLIENT_SECRET

If Cursor doesn't show the Keycloak tools or shows "no tools, prompts or resources":

1. Verify the .cursor/mcp.json file exists in your project root
2. Check the absolute path is correct in the config file
3. Ensure the project is built: npm run build
4. Restart Cursor completely - close all windows and reopen
5. Check Cursor's MCP logs for any error messages
6. Test the server manually:

   cd /path/to/keycloak-mcp-entrypoint
   npm start

   You should see successful Keycloak connection messages

If Claude Desktop doesn't show the Keycloak tools:

1. Verify the absolute path in claude_desktop_config.json is correct:

   # Get the correct path
   cd /path/to/keycloak-mcp-entrypoint
   pwd
   # Then append /dist/index.js to this path

2. Ensure the project is built:

   npm run build

   Verify dist/index.js exists.

3. Test the server manually first:

   npm start

   Make sure it connects successfully before adding to Claude Desktop.

4. Completely quit and restart Claude Desktop (not just reload):

   • macOS: Cmd+Q to quit, then reopen
   • Windows: File → Exit, then reopen
   • Linux: Close all windows, then reopen

5. Check Claude Desktop logs for errors:

   • macOS: ~/Library/Logs/Claude/mcp*.log
   • Windows: %APPDATA%\Claude\logs\mcp*.log
   • Linux: ~/.config/Claude/logs/mcp*.log

6. Verify JSON syntax is correct:

   • Use a JSON validator to check your config file
   • Make sure there are no trailing commas
   • Ensure proper quote escaping (especially on Windows paths: use \\)

If the build fails:

1. Ensure another-keycloak-mcp is built: cd ../another-keycloak-mcp && npm run build
2. Clean and rebuild: npm run clean && npm install && npm run build
3. Check Node.js version: node --version (requires >= 18.0.0)

MIT