Clerk MCP Server Template

Clerk MCP サーバーテンプレート

Cloudflare Workers 上で Clerk 認証を使用する Model Context Protocol（MCP）サーバーを構築するための、本番環境対応テンプレートです。このテンプレートを使えば、既存の Clerk 対応アプリケーションと連携する、安全な認証済み MCP ツールを作成できます。

機能

• ✅ Clerk 認証の統合 - Clerk による完全な OAuth 2.0 フロー
• ✅ Cloudflare Workers - グローバルに分散されたサーバーレスエッジコンピューティング
• ✅ Durable Objects - MCP セッション状態の永続的な管理
• ✅ KV ストレージ - OAuth セッションの一時ストレージ
• ✅ セキュリティ - HMAC 署名付き状態パラメーターと自動トークン更新
• ✅ TypeScript - コードベース全体にわたる完全な型安全性
• ✅ ツールの例 - すぐに使える MCP ツールの例
• ✅ 開発ツール - ESLint、Prettier、MCP Inspector の統合

このテンプレートを選ぶ理由

このテンプレートを使うと、既存の Clerk 認証済みアプリケーションと Claude AI を MCP ツールで連携できます。次の用途に最適です。

• 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 には、MCP 認証フローを実装する既存の Clerk 認証済みアプリケーションの URL を指定してください。

4. KV 名前空間を作成する

OAuth セッションを保存する KV 名前空間を作成します。

wrangler kv:namespace create "OAUTH_KV"

生成された名前空間 ID で wrangler.jsonc の id を更新します。

5. 設定を更新する

wrangler.jsonc：

• name の "your-mcp-server" を、任意の Worker 名に変更します
• 生成した 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 エンドポイントを作成する

MCP サーバーが認証済みリクエストで呼び出せる、保護された API エンドポイントをアプリケーションに追加します。

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 Dashboard で JWT テンプレートを作成します。

1. Clerk Dashboard の 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 Dashboard に 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. このリポジトリをフォークします
2. フィーチャーブランチを作成します：git checkout -b feature/amazing-feature
3. 変更をコミットします：git commit -m 'Add amazing feature'
4. ブランチにプッシュします：git push origin feature/amazing-feature
5. プルリクエストを作成します

リソース

• Model Context Protocol 仕様
• Clerk 認証ドキュメント
• Cloudflare Workers ドキュメント
• Cloudflare MCP の例
• React Router v7 ドキュメント

ライセンス

MIT ライセンスの詳細については、LICENSE ファイルを参照してください。