Local Keycloak for FastMCP

Local Keycloak companion for FastMCP — everything you need to develop and test FastMCP servers with Keycloak OAuth locally, without adding infrastructure burden to the core library.

• Why This Project Exists
• Requirements
• Quick Start
  • 1. Start Keycloak
  • 2. Install FastMCP
  • 3. Run the Server
  • 4. Test
• MCP Client Compatibility
• Using with Claude Desktop and Claude Code CLI
  • Prerequisites
  • Claude Desktop
  • Claude Code CLI

Why This Project Exists

FastMCP ships a Keycloak auth provider — introduced in PR #1937 — that lets you protect MCP servers with Keycloak OAuth using only a realm URL and a JWTVerifier. The PR also included a Docker-based local Keycloak setup as a bonus — letting developers test the full OAuth flow instantly, without relying on any external service.

However, the local setup — Docker Compose configuration, pre-configured realm, extended docs, MCP Inspector compatibility notes, Claude Desktop integration guidance — is maintenance surface that belongs outside the core library. FastMCP's maintainers were clear: the auth provider itself belongs in core, the infrastructure tooling does not (discussion). That stance is fully justified: FastMCP's focus is FastMCP, not FastAuth, and keeping the core lean means not carrying long-term maintenance for third-party infrastructure that varies by environment, version, and deployment topology.

This project is that externalized local Keycloak setup. It gives you:

• A one-command local Keycloak instance (Docker Compose, pre-configured fastmcp realm)
• Dynamic Client Registration ready for native MCP clients (Python SDK, Claude Desktop, Claude Code CLI)
• A pre-registered mcp-inspector client for browser-based testing via the MCP Inspector
• Cross-platform start scripts (.sh for macOS/Linux/WSL, .ps1 for Windows)

Requirements

• Python 3.10+ with fastmcp installed (pip install fastmcp)
• Keycloak 26.6.0+ (local Docker or existing instance)
• Docker & Docker Compose (for local setup)

Quick Start

1. Start Keycloak

macOS / Linux / WSL:

cd examples/auth/keycloak_oauth/keycloak
./start-keycloak.sh

Windows (PowerShell):

cd examples/auth/keycloak_oauth/keycloak
.\start-keycloak.ps1

This starts Keycloak on port 8080 and automatically imports the fastmcp realm with:

• Dynamic Client Registration configured for http://localhost:8000/*
• A pre-registered mcp-inspector client for browser-based testing
• A test user (testuser / password123)

2. Install FastMCP

pip install fastmcp

3. Run the Server

cd examples/auth/keycloak_oauth
python server.py

4. Test

Python client:

python client.py

MCP Inspector:

npx -y @modelcontextprotocol/inspector

• Transport: Streamable HTTP
• Connection: Direct
• URL: http://localhost:8000/mcp
• In the Authentication section's OAuth 2.0 Flow area: Client ID mcp-inspector

See examples/auth/keycloak_oauth/README.md for full instructions.

MCP Client Compatibility

Note (browser-based clients / MCP Inspector): Keycloak only adds CORS headers to the DCR endpoint when the request includes an Initial Access Token explicitly configured with allowed web origins. The MCP spec has no concept of Initial Access Tokens, so all MCP clients perform open DCR without one — browser-based clients therefore get no CORS headers and the DCR request fails.

As a workaround, the preconfigured Keycloak realm provided in this repository ships with a pre-registered mcp-inspector client that bypasses DCR entirely and has webOrigins: ["http://localhost:6274"] set. This is the correct long-term pattern for browser-based MCP clients — see examples/auth/keycloak_oauth/keycloak/README.md for the full explanation.

Using with Claude Desktop and Claude Code CLI

Both Claude Desktop and Claude Code CLI are native (non-browser) clients, so Dynamic Client Registration succeeds without any CORS workarounds and no pre-registered client ID is needed. Claude Code CLI has native HTTP transport support. Claude Desktop does not — it requires mcp-remote as a stdio bridge.

Prerequisites

Keycloak and the example server must both be running:

# Terminal 1 — Keycloak
cd examples/auth/keycloak_oauth/keycloak && ./start-keycloak.sh

# Terminal 2 — FastMCP server
cd examples/auth/keycloak_oauth && python server.py

Claude Desktop

Claude Desktop's claude_desktop_config.json only supports stdio-based MCP servers — it cannot connect directly to HTTP MCP servers. Web connectors (HTTP transport) are only available through the built-in Connectors UI, which requires a public HTTPS URL and does not support localhost. To connect to a local HTTP MCP server, use mcp-remote as a bridge (requires Node.js):

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

{
  "mcpServers": {
    "keycloak-example": {
      "command": "npx",
      "args": ["mcp-remote", "http://localhost:8000/mcp"]
    }
  }
}

Restart Claude Desktop. On first use, mcp-remote will open your browser to complete the Keycloak login flow (testuser / password123). After authorizing, Claude can call the protected tools.

Claude Code CLI

Run this once in your terminal to register the server globally (user scope — available in every Claude Code session, regardless of working directory):

claude mcp add --scope user --transport http keycloak-example http://localhost:8000/mcp

Or add it to your project's .mcp.json to share it with the team (project scope, committed to version control):

{
  "mcpServers": {
    "keycloak-example": {
      "url": "http://localhost:8000/mcp"
    }
  }
}

On first use, Claude Code will prompt you to open a browser to complete the OAuth authorization with Keycloak. After that, the access token is cached and reused for subsequent requests.