Clerk MCP Server Template

Clerk MCP 服务模板

一个可在 Cloudflare Workers 上构建带 Clerk 身份验证的 Model Context Protocol（MCP）服务的生产就绪模板。本模板提供创建安全、经过身份验证的 MCP 工具所需的一切，可与现有的 Clerk 应用集成。

功能

• ✅ Clerk 身份验证集成 - 使用 Clerk 的完整 OAuth 2.0 流程
• ✅ Cloudflare Workers - 具有全球分发能力的无服务器边缘计算
• ✅ Durable Objects - 持久化 MCP 会话状态管理
• ✅ KV 存储 - 临时 OAuth 会话存储
• ✅ 安全性 - HMAC 签名的状态参数和自动令牌刷新
• ✅ TypeScript - 整个代码库具备完整的类型安全
• ✅ 示例工具 - 可直接使用的 MCP 工具示例
• ✅ 开发工具 - 集成 ESLint、Prettier 和 MCP Inspector

为什么选择此模板？

此模板通过 MCP 工具，将现有的 Clerk 身份验证应用与 Claude AI 连接起来。适用于：

• SaaS 应用：让 Claude 访问你的用户数据和业务逻辑
• 客户支持：让 Claude 在适当的用户上下文中查询你的系统
• 数据分析：为 Claude 提供经过身份验证的 API 访问权限
• 工作流自动化：创建安全、针对特定用户的自动化流程

快速开始

1. 先决条件

• Node.js 22.x 或更高版本
• 一个带有 API 密钥的 Clerk 账户
• 一个已启用 Workers 的 Cloudflare 账户
• 一个使用 Clerk 进行身份验证的现有应用

2. 使用此模板

git clone https://github.com/your-username/clerk-mcp-template.git my-mcp-server
cd my-mcp-server
npm install

3. 配置环境变量

复制示例环境文件：

cp .dev.vars.example .dev.vars

在 .dev.vars 中填写你的 Clerk 密钥和应用 URL：

CLERK_SECRET_KEY=sk_test_your_actual_clerk_secret_key
CLERK_PUBLISHABLE_KEY=pk_test_your_actual_clerk_publishable_key
APP_URL=https://your-app.com

重要提示：APP_URL 应指向你现有的 Clerk 身份验证应用，你将在该应用中实现 MCP 身份验证流程。

4. 创建 KV 命名空间

创建一个用于存储 OAuth 会话的 KV 命名空间：

wrangler kv:namespace create "OAUTH_KV"

使用生成的命名空间 ID 更新 wrangler.jsonc 中的 id。

5. 更新配置

wrangler.jsonc：

• 将 name 从 "your-mcp-server" 改为你想要的 Worker 名称
• 使用上面生成的 ID 更新 KV 命名空间 ID

src/index.ts：

• 在 McpServer 构造函数中更新服务名称和版本
• 将示例工具替换为你自己的工具（参见下方示例）

6. 启动开发

npm run dev

服务将在 http://localhost:8788 上运行。

架构

graph TB
    A[MCP Client] --> B[Cloudflare Worker]
    B --> C[OAuth Provider]
    C --> D[Clerk Authentication]
    B --> E[Durable Objects]
    B --> F[KV Storage]
    B --> G[Your API]

    E --> H[MCP Session State]
    F --> I[OAuth Sessions]
    D --> J[User Authentication]
    G --> K[Your Application Data]

身份验证流程

1. MCP 客户端连接到 /sse 端点
2. OAuth 重定向到 /authorize 端点
3. 用户身份验证通过 Clerk 完成（此部分由你实现）
4. 在 /callback 端点进行令牌交换
5. 在 Durable Objects 中创建会话
6. MCP 工具在经过身份验证的上下文中可用

与应用集成

步骤 1：添加 MCP 身份验证路由

在现有 Clerk 应用中创建 /auth/mcp 身份验证路由。此路由负责处理 MCP 服务发起的 OAuth 流程。

React Router v7（框架模式）示例

此示例展示了如何在框架模式（以前称为 Remix）下与 React Router v7 集成；你也可以根据 Next.js、Express 或其他框架进行调整。

app/routes/auth.mcp.tsx：

import { createClerkClient } from '@clerk/express'
import { redirect, type LoaderFunctionArgs } from 'react-router'

export async function loader({ request }: LoaderFunctionArgs) {
	const url = new URL(request.url)
	const state = url.searchParams.get('state')
	const callbackUrl = url.searchParams.get('callback_url')
	const clientName = url.searchParams.get('client_name')

	if (!state || !callbackUrl) {
		throw new Error('Missing required parameters')
	}

	// Get the authenticated user's session token
	const clerkClient = createClerkClient({
		secretKey: process.env.CLERK_SECRET_KEY,
		publishableKey: process.env.CLERK_PUBLISHABLE_KEY,
	})

	const clerkAuth = (await clerkClient.authenticateRequest(request)).toAuth()
	const sessionToken = await clerkAuth?.getToken()

	if (!sessionToken) {
		// Redirect to sign-in if not authenticated
		const signInUrl = new URL('/sign-in', request.url)
		signInUrl.searchParams.set('redirect_url', request.url)
		return redirect(signInUrl.toString())
	}

	// Redirect back to MCP server with token
	const redirectUrl = new URL(callbackUrl)
	redirectUrl.searchParams.set('clerk_token', sessionToken)
	redirectUrl.searchParams.set('state', state)

	return redirect(redirectUrl.toString())
}

// Optional: Add a component for showing consent screen
export default function McpAuth() {
	return (
		<div className="max-w-md mx-auto mt-8 p-6 bg-white rounded-lg shadow-md">
			<h1 className="text-xl font-bold mb-4">Authorize MCP Access</h1>
			<p className="text-gray-600 mb-4">
				Claude AI is requesting access to your account data.
			</p>
			<p className="text-sm text-gray-500">
				This will redirect you automatically...
			</p>
		</div>
	)
}

步骤 2：创建 API 端点

在应用中添加受保护的 API 端点，供 MCP 服务通过经过身份验证的请求调用。

app/routes/api.users.tsx：

import { createClerkClient } from '@clerk/express'
import { json, type LoaderFunctionArgs } from 'react-router'

export async function loader({ request }: LoaderFunctionArgs) {
	try {
		const clerkClient = createClerkClient({
			secretKey: process.env.CLERK_SECRET_KEY,
			publishableKey: process.env.CLERK_PUBLISHABLE_KEY,
		})

		// Verify the request is authenticated
		const clerkAuth = await clerkClient.authenticateRequest(request)
		const userId = clerkAuth.toAuth()?.userId

		if (!userId) {
			return json({ error: 'Unauthorized' }, { status: 401 })
		}

		// Your business logic here
		const users = await getUsersForCurrentUser(userId)

		return { users }
	} catch (error) {
		return json({ error: 'Internal server error' }, { status: 500 })
	}
}

步骤 3：自定义 MCP 工具

将 src/index.ts 中的示例工具替换为你自己的工具：

// Custom tool example
this.server.tool(
	'getUsers',
	'Fetch all users from your application',
	{},
	this.requireAuth(async () => {
		const users = await this.makeApiRequest('api/users')

		return {
			content: [
				{
					type: 'text',
					text: `Found ${users.length} users:\n${JSON.stringify(users, null, 2)}`,
				},
			],
		}
	}),
)

配置参考

环境变量

变量	描述	必需
CLERK_SECRET_KEY	你的 Clerk 密钥	✅
CLERK_PUBLISHABLE_KEY	你的 Clerk 公钥	✅
APP_URL	你的应用 URL	✅

在 src/types.ts 的 Env 接口中添加你自己的应用专属环境变量。

Clerk JWT 模板

在 Clerk 控制面板中创建一个用于生成令牌的 JWT 模板：

1. 前往 Clerk 控制面板中的 JWT Templates
2. 创建一个新模板（例如，“mcp-server”）
3. 在 src/index.ts 中更新模板名称：

const token = await getToken(
	// ... token manager
	(this as any).env.CLERK_SECRET_KEY,
	'your-template-name', // Update this
)

开发

可用脚本

npm run dev        # Start development server
npm run deploy     # Deploy to Cloudflare Workers
npm run inspect    # Launch MCP Inspector
npm run lint       # Run ESLint + format
npm run typecheck  # Run TypeScript type checking
npm run validate   # Run typecheck + lint

使用 MCP Inspector 进行测试

1. 启动开发服务器：npm run dev
2. 打开 MCP Inspector
3. 将传输类型设为 SSE
4. 连接到 http://localhost:8788/sse
5. 完成身份验证流程
6. 测试你的工具

部署

1. 设置生产环境密钥

wrangler secret put CLERK_SECRET_KEY
wrangler secret put CLERK_PUBLISHABLE_KEY
wrangler secret put APP_URL

2. 创建生产环境 KV 命名空间

wrangler kv:namespace create "OAUTH_KV" --env production

在 wrangler.jsonc 中更新生产环境 KV 命名空间 ID。

3. 部署和配置

npm run deploy

将已部署的服务添加到 Claude Desktop MCP 配置中：

{
	"mcpServers": {
		"my-app": {
			"command": "npx",
			"args": [
				"@modelcontextprotocol/server-remote",
				"https://your-mcp-server.your-subdomain.workers.dev/sse"
			]
		}
	}
}

项目结构

clerk-mcp-template/
├── src/
│   ├── index.ts      # Main MCP server class and tools
│   ├── auth.ts       # OAuth authentication handlers
│   ├── clerk.ts      # Clerk authentication utilities
│   ├── utils.ts      # Utility functions (HMAC, logging, etc.)
│   └── types.ts      # TypeScript type definitions
├── wrangler.jsonc    # Cloudflare Worker configuration
├── package.json      # Dependencies and scripts
├── tsconfig.json     # TypeScript configuration
├── eslint.config.js  # ESLint configuration
├── .dev.vars         # Development environment variables
└── README.md         # This file

安全注意事项

• OAuth 2.0 可确保安全的身份验证流程
• HMAC 签名 可保护状态参数免遭篡改
• 自动刷新令牌 可处理会话过期
• 会话清理 会移除过期的 OAuth 会话
• 安全标头 包含适当的 CORS 和身份验证标头

故障排除

常见问题

身份验证失败：

• 确认 Clerk API 密钥正确
• 确保已实现身份验证路由
• 检查 Clerk 控制面板中是否存在 JWT 模板

KV 命名空间错误：

• 确认 wrangler.jsonc 中的命名空间 ID
• 确保已创建并绑定命名空间

工具无法运行：

• 检查用户是否已通过身份验证
• 确认 API 端点正确
• 查看 Cloudflare Workers 日志

调试

# View real-time logs
wrangler tail

# Check deployment status
wrangler deployments list

# Test locally with debugging
npm run dev

贡献

1. Fork 此仓库
2. 创建功能分支：git checkout -b feature/amazing-feature
3. 提交更改：git commit -m 'Add amazing feature'
4. 推送到分支：git push origin feature/amazing-feature
5. 创建 Pull Request

资源

• Model Context Protocol 规范
• Clerk 身份验证文档
• Cloudflare Workers 文档
• Cloudflare MCP 示例
• React Router v7 文档

许可证

MIT 许可证 — 详情请参阅 LICENSE 文件。