Clerk MCP Server

MCP服务器职员

A. 模型上下文协议（MCP） 服务器 职员

直接从人工智能助手（如Claude、Cursor、VS Code Copilot、Windsurf等）查询和管理您的职员组织、成员、用户、角色和元数据。

______________________________________________________________________

获取办事员API密钥

你需要一个 职员密钥 使用此服务器。

1. 首选 dashboard.clerk.com 登录（或创建帐户）
2. 选择您的应用程序（或创建一个）
3. 引导到 配置 → API密钥
4. 复制 密钥 --它始于 sk_test_ （开发）或 sk_live_ （生产）

永远不要将你的密钥提交给git。 使用环境变量或通过标头传递它。

______________________________________________________________________

两种操作模式

服务器支持两种模式，启动时自动检测：

托管模式（私人）

服务器拥有Clerk密钥。集 CLERK_SECRET_KEY 在你的 .env 文件和所有请求都使用该密钥。不需要来自客户端的标头。

最适合： 个人使用、内部团队、自托管部署。

公共模式（按请求密钥）

服务器上没有密钥。每个客户端通过 X-Clerk-Secret-Key 每个请求上的HTTP标头。服务器根据请求创建一个新的Clerk客户端。

最适合： 共享部署、多租户设置，或者当您不希望密钥存储在服务器上时。

______________________________________________________________________

快速开始

1.克隆并安装

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

2.配置并运行

托管模式 --在服务器上设置一次密钥：

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

公共模式 --没有 .env 需要时，客户提供密钥：

npm run dev

您的MCP端点现在位于 https://clerk-mcp.vercel.app/mcp.

3.验证

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

• 托管模式: {"status":"ok","mode":"hosted","clerkConnected":true}
• 公共模式: {"status":"ok","mode":"public","clerkConnected":null}

______________________________________________________________________

连接到AI助手

克劳德代码（CLI）

托管模式：

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

公共模式：

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

克劳德桌面

增添 ~/Library/Application Support/Claude/claude_desktop_config.json （macOS）或 %APPDATA%\Claude\claude_desktop_config.json （Windows）：

托管模式：

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

公共模式：

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

光标

首选 设置→ MCP → 添加服务器:

托管模式：

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

公共模式：

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

VS代码（GitHub副本）

添加到您的工作区 .vscode/mcp.json:

托管模式：

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

公共模式：

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

帆板运动

添加到MCP设置：

托管模式：

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

公共模式：

{
  "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 -t clerk-mcp .

在托管模式下运行

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

以公共模式运行

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

Docker Compose

这两种模式的定义见 docker-compose.yml:

# 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

______________________________________________________________________

可用工具

组织

成员

邀请函

用户

______________________________________________________________________

示例提示

连接后，尝试询问您的AI助手：

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".

______________________________________________________________________

部署到生产

构建并部署为任何Nuxt/Node.js应用程序：

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

或者使用Docker：

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

如果您自托管，请使用您自己的部署URL，而不是 https://clerk-mcp.vercel.app 在上面的客户端配置中。

兼容： 维塞尔, Netlify, Cloudflare员工 （预设硝基）， 铁路, Fly.io，或任何Node.js主机。

______________________________________________________________________

添加新工具

在中创建新文件 server/mcp/tools/ --它由MCP工具包自动发现：

// 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);
  },
});

技术栈

• Nuxt 4 --全栈Vue框架
• @nuxtjs/mcp工具包 --Nuxt的MCP服务器模块
• @职员/后台 --职员后端SDK
• 佐德 --架构验证

许可证

麻省理工学院