# Clerk MCP Server

A [Model Context Protocol (MCP)](https://modelcontextprotocol.io/) server for [Clerk](https://clerk.com)

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](https://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.

|                      | Hosted Mode          | Public Mode             |
| -------------------- | -------------------- | ----------------------- |
| Key stored on server | Yes (in `.env`)      | No                      |
| Key sent per request | No                   | Yes (via header)        |
| Setup complexity     | Simpler              | Slightly more config    |
| Multi-user support   | Single Clerk account | Multiple Clerk accounts |

---

## Quick Start

### 1. Clone & install

```bash
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:

```bash
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:

```bash
npm run dev
```

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

### 3. Verify

```bash
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:**

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

**Public mode:**

```bash
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:**

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

**Public mode:**

```json
{
  "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:**

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

**Public mode:**

```json
{
  "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:**

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

**Public mode:**

```json
{
  "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:**

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

**Public mode:**

```json
{
  "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": {}
    }
  }
}
```

---

## Docker

### Build the image

```bash
docker build -t clerk-mcp .
```

### Run in hosted mode

```bash
docker run -d -p 3000:3000 -e CLERK_SECRET_KEY=sk_test_xxxxxxxxxxxxxxxxxxxxxxxxxxxxx clerk-mcp
```

### Run in public mode

```bash
docker run -d -p 3000:3000 clerk-mcp
```

### Docker Compose

Both modes are defined in `docker-compose.yml`:

```bash
# Hosted mode on port 3000 — set CLERK_SECRET_KEY in .env first
docker compose up clerk-mcp-hosted

# Public mode on port 3001 — no key needed on the server
docker compose up clerk-mcp-public
```

---

## Available Tools

### Organizations

| Tool                                 | Description                                                          |
| ------------------------------------ | -------------------------------------------------------------------- |
| `clerk_list_organizations`           | List orgs with filtering by name/slug, pagination, and member counts |
| `clerk_get_organization`             | Get org details by ID or slug (includes metadata, timestamps)        |
| `clerk_create_organization`          | Create a new organization with name, slug, and metadata              |
| `clerk_update_organization_metadata` | Update org public/private metadata                                   |
| `clerk_delete_organization`          | Delete an organization permanently (irreversible)                    |

### Members

| Tool                              | Description                                             |
| --------------------------------- | ------------------------------------------------------- |
| `clerk_list_organization_members` | List org members with roles, user data, and metadata    |
| `clerk_update_member_role`        | Change a member's role (e.g. `org:admin`, `org:member`) |
| `clerk_update_member_metadata`    | Update membership public/private metadata               |
| `clerk_remove_member`             | Remove a member from an organization                    |

### Invitations

| Tool                                  | Description                                           |
| ------------------------------------- | ----------------------------------------------------- |
| `clerk_list_organization_invitations` | List invitations by status (pending/accepted/revoked) |
| `clerk_create_invitation`             | Invite a user to an org by email                      |

### Users

| Tool                         | Description                                                        |
| ---------------------------- | ------------------------------------------------------------------ |
| `clerk_list_users`           | List all instance users with search by name/email/phone            |
| `clerk_get_user`             | Get full user profile: emails, phones, external accounts, metadata |
| `clerk_update_user_metadata` | Update user public/private/unsafe metadata                         |

---

## Example Prompts

Once connected, try asking your AI assistant:

```
List all organizations in my Clerk instance.
How many members does the "engineering" organization have?
Create a new organization called "Design Team" with slug "design-team".
Show me all pending invitations for organization org_2abc123.
Find all users with email addresses containing "@example.com".
Update the public metadata for user user_2xyz789 to set plan: "pro".
```

---

## Deploying to Production

Build and deploy as any Nuxt/Node.js app:

```bash
npm run build
node .output/server/index.mjs
```

Or use Docker:

```bash
docker build -t clerk-mcp .
docker run -p 3000:3000 -e CLERK_SECRET_KEY=sk_live_xxx clerk-mcp
```

If you self-host, use your own deployment URL instead of `https://clerk-mcp.vercel.app` in the client configs above.

Compatible with: **Vercel**, **Netlify**, **Cloudflare Workers** (with nitro preset), **Railway**, **Fly.io**, or any Node.js host.

---

## Adding New Tools

Create a new file in `server/mcp/tools/` — it's automatically discovered by the MCP toolkit:

```typescript
// server/mcp/tools/clerk-my-new-tool.ts
import { z } from "zod";

export default defineMcpTool({
  name: "clerk_my_new_tool",
  description: "Description of what this tool does",
  inputSchema: {
    param: z.string().describe("Parameter description"),
  },
  annotations: {
    readOnlyHint: true,
    destructiveHint: false,
    openWorldHint: true,
  },
  async handler({ param }) {
    const clerk = useClerkClient();
    const result = await clerkCall(() => clerk.someApi.someMethod({ param }));
    return jsonResult(result);
  },
});
```

## Tech Stack

- [Nuxt 4](https://nuxt.com) — Full-stack Vue framework
- [@nuxtjs/mcp-toolkit](https://mcp-toolkit.nuxt.dev) — MCP server module for Nuxt
- [@clerk/backend](https://clerk.com/docs/reference/backend/overview) — Clerk Backend SDK
- [Zod](https://zod.dev) — Schema validation

## License

MIT