Clerk MCP Server

Clerk MCP Server

A Model Context Protocol (MCP) server for Clerk

Query and manage your Clerk organizations, members, users, roles, and metadata directly from AI assistants like Claude, Cursor, VS Code Copilot, Windsurf, and more.

Getting Your Clerk API Key

You need a Clerk Secret Key to use this server.

1. Go to dashboard.clerk.com and sign in (or create an account)
2. Select your application (or create one)
3. Navigate to Configure → API Keys
4. Copy the Secret Key — it starts with sk_test_ (development) or sk_live_ (production)

Never commit your secret key to git. Use environment variables or pass it via headers.

Two Operating Modes

The server supports two modes, auto-detected at startup:

Hosted Mode (Private)

The server owns the Clerk secret key. Set CLERK_SECRET_KEY in your .env file and all requests use that single key. No headers needed from clients.

Best for: Personal use, internal teams, self-hosted deployments.

Public Mode (Per-Request Key)

No secret key on the server. Each client passes their own key via the X-Clerk-Secret-Key HTTP header on every request. The server creates a fresh Clerk client per request.

Best for: Shared deployments, multi-tenant setups, or when you don't want the key stored on the server.

Quick Start

1. Clone & install

git clone https://github.com/BalajiSriraman/Clerk-MCP.git
cd Clerk-MCP
npm install

2. Configure & run

Hosted mode — set the key once on the server:

cp .env.example .env
# Edit .env and paste your secret key:
# CLERK_SECRET_KEY=sk_test_xxxxxxxxxxxxxxxxxxxxxxxxxxxxx
npm run dev

Public mode — no .env needed, clients provide the key:

npm run dev

Your MCP endpoint is now live at https://clerk-mcp.vercel.app/mcp.

3. Verify

curl https://clerk-mcp.vercel.app/api/health

• Hosted mode: {"status":"ok","mode":"hosted","clerkConnected":true}
• Public mode: {"status":"ok","mode":"public","clerkConnected":null}

Connect to AI Assistants

Claude Code (CLI)

Hosted mode:

claude mcp add --transport http clerk https://clerk-mcp.vercel.app/mcp

Public mode:

claude mcp add --transport http \
  --header "X-Clerk-Secret-Key: sk_test_xxxxxxxxxxxxxxxxxxxxxxxxxxxxx" \
  clerk https://clerk-mcp.vercel.app/mcp

Claude Desktop

Add to ~/Library/Application Support/Claude/claude_desktop_config.json (macOS) or %APPDATA%\Claude\claude_desktop_config.json (Windows):

Hosted mode:

{
  "mcpServers": {
    "clerk": {
      "command": "npx",
      "args": ["mcp-remote", "https://clerk-mcp.vercel.app/mcp"]
    }
  }
}

Public mode:

{
  "mcpServers": {
    "clerk": {
      "command": "npx",
      "args": [
        "mcp-remote",
        "https://clerk-mcp.vercel.app/mcp",
        "--header",
        "X-Clerk-Secret-Key: sk_test_xxxxxxxxxxxxxxxxxxxxxxxxxxxxx"
      ]
    }
  }
}

Cursor

Go to Settings → MCP → Add Server:

Hosted mode:

{
  "mcpServers": {
    "clerk": {
      "url": "https://clerk-mcp.vercel.app/mcp"
    }
  }
}

Public mode:

{
  "mcpServers": {
    "clerk": {
      "url": "https://clerk-mcp.vercel.app/mcp",
      "headers": {
        "X-Clerk-Secret-Key": "sk_test_xxxxxxxxxxxxxxxxxxxxxxxxxxxxx"
      }
    }
  }
}

VS Code (GitHub Copilot)

Add to your workspace .vscode/mcp.json:

Hosted mode:

{
  "mcp": {
    "servers": {
      "clerk": {
        "url": "https://clerk-mcp.vercel.app/mcp"
      }
    }
  }
}

Public mode:

{
  "mcp": {
    "servers": {
      "clerk": {
        "url": "https://clerk-mcp.vercel.app/mcp",
        "headers": {
          "X-Clerk-Secret-Key": "sk_test_xxxxxxxxxxxxxxxxxxxxxxxxxxxxx"
        }
      }
    }
  }
}

Windsurf

Add to MCP settings:

Hosted mode:

{
  "context_servers": {
    "clerk": {
      "source": "custom",
      "command": "npx",
      "args": ["mcp-remote", "https://clerk-mcp.vercel.app/mcp"],
      "env": {}
    }
  }
}

Public mode:

{
  "context_servers": {
    "clerk": {
      "source": "custom",
      "command": "npx",
      "args": [
        "mcp-remote",
        "https://clerk-mcp.vercel.app/mcp",
        "--header",
        "X-Clerk-Secret-Key: sk_test_xxxxxxxxxxxxxxxxxxxxxxxxxxxxx"
      ],
      "env": {}
    }
  }
}

--