From 5e959a4309fa019ec4d87b70cbc7ceead842076a Mon Sep 17 00:00:00 2001 From: Mitchel Vostrez Date: Fri, 19 Dec 2025 15:52:39 -0600 Subject: [PATCH] feat(mcp): add mcp-server package --- packages/mcp-server/LICENSE | 21 ++++++++ packages/mcp-server/README.md | 83 ++++++++++++++++++++++++++++++ packages/mcp-server/package.json | 39 ++++++++++++++ packages/mcp-server/src/cli.ts | 8 +++ packages/mcp-server/tsconfig.json | 19 +++++++ packages/mcp-server/tsup.config.ts | 24 +++++++++ pnpm-lock.yaml | 2 + 7 files changed, 196 insertions(+) create mode 100644 packages/mcp-server/LICENSE create mode 100644 packages/mcp-server/README.md create mode 100644 packages/mcp-server/package.json create mode 100644 packages/mcp-server/src/cli.ts create mode 100644 packages/mcp-server/tsconfig.json create mode 100644 packages/mcp-server/tsup.config.ts diff --git a/packages/mcp-server/LICENSE b/packages/mcp-server/LICENSE new file mode 100644 index 00000000000..49e46cae156 --- /dev/null +++ b/packages/mcp-server/LICENSE @@ -0,0 +1,21 @@ +MIT License + +Copyright (c) 2025 Clerk, Inc. + +Permission is hereby granted, free of charge, to any person obtaining a copy +of this software and associated documentation files (the "Software"), to deal +in the Software without restriction, including without limitation the rights +to use, copy, modify, merge, publish, distribute, sublicense, and/or sell +copies of the Software, and to permit persons to whom the Software is +furnished to do so, subject to the following conditions: + +The above copyright notice and this permission notice shall be included in all +copies or substantial portions of the Software. + +THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR +IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, +FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE +AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER +LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, +OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE +SOFTWARE. diff --git a/packages/mcp-server/README.md b/packages/mcp-server/README.md new file mode 100644 index 00000000000..3980d1a8fb0 --- /dev/null +++ b/packages/mcp-server/README.md @@ -0,0 +1,83 @@ +

+ + + + + + +
+

@clerk/mcp-server

+

+ +
+ +[![Chat on Discord](https://img.shields.io/discord/856971667393609759.svg?logo=discord)](https://clerk.com/discord) +[![Clerk documentation](https://img.shields.io/badge/documentation-clerk-green.svg)](https://clerk.com/docs?utm_source=github&utm_medium=clerk_mcp_server) +[![Follow on Twitter](https://img.shields.io/twitter/follow/ClerkDev?style=social)](https://twitter.com/intent/follow?screen_name=ClerkDev) + +[Changelog](https://github.com/clerk/javascript/blob/main/packages/mcp-server/CHANGELOG.md) +· +[Report a Bug](https://github.com/clerk/javascript/issues/new?assignees=&labels=needs-triage&projects=&template=BUG_REPORT.yml) +· +[Request a Feature](https://feedback.clerk.com/roadmap) +· +[Get Help](https://clerk.com/contact/support?utm_source=github&utm_medium=clerk_mcp_server) + +
+ +## Overview + +Connect to Clerk's remote MCP (Model Context Protocol) server from any MCP-compatible client like Claude Desktop. This package provides a thin wrapper that proxies stdio communication to Clerk's hosted MCP server at `https://mcp.clerk.com`. + +## Quick Start + +Run directly with npx: + +```bash +npx @clerk/mcp-server +``` + +## Usage with MCP configuration + +Add the following to your MCP configuration file: + +```json +{ + "mcpServers": { + "clerk": { + "command": "npx", + "args": ["-y", "@clerk/mcp-server"] + } + } +} +``` + +## Prerequisites + +- Node.js 18 or higher +- An MCP-compatible client (e.g., Claude Desktop, Cursor, etc.) + +## How It Works + +This package acts as a bridge between stdio-based MCP clients and Clerk's remote MCP server: + +1. Your MCP client (e.g., Claude Desktop) communicates with this package via stdio +2. This package forwards requests to `https://mcp.clerk.com/mcp` via HTTP +3. Responses are proxied back to your client + +## Support + +You can get in touch with us in any of the following ways: + +- Join our official community [Discord server](https://clerk.com/discord) +- On [our support page](https://clerk.com/contact/support?utm_source=github&utm_medium=clerk_mcp_server) + +## Contributing + +We're open to all community contributions! If you'd like to contribute in any way, please read [our contribution guidelines](https://github.com/clerk/javascript/blob/main/docs/CONTRIBUTING.md) and [code of conduct](https://github.com/clerk/javascript/blob/main/docs/CODE_OF_CONDUCT.md). + +## License + +This project is licensed under the **MIT license**. + +See [LICENSE](https://github.com/clerk/javascript/blob/main/packages/mcp-server/LICENSE) for more information. diff --git a/packages/mcp-server/package.json b/packages/mcp-server/package.json new file mode 100644 index 00000000000..b9a1d86f811 --- /dev/null +++ b/packages/mcp-server/package.json @@ -0,0 +1,39 @@ +{ + "name": "@clerk/mcp-server", + "version": "0.0.0", + "description": "Connect to Clerk's remote MCP server via stdio", + "homepage": "https://clerk.com/", + "bugs": { + "url": "https://github.com/clerk/javascript/issues" + }, + "repository": { + "type": "git", + "url": "git+https://github.com/clerk/javascript.git", + "directory": "packages/mcp-server" + }, + "license": "MIT", + "author": "Clerk", + "type": "module", + "main": "dist/cli.js", + "bin": { + "clerk-mcp": "dist/cli.js" + }, + "files": [ + "dist" + ], + "scripts": { + "build": "tsup --env.NODE_ENV production", + "clean": "rimraf ./dist", + "dev": "tsup --watch", + "format": "node ../../scripts/format-package.mjs", + "format:check": "node ../../scripts/format-package.mjs --check", + "lint": "eslint src" + }, + "devDependencies": {}, + "engines": { + "node": ">=20" + }, + "publishConfig": { + "access": "public" + } +} diff --git a/packages/mcp-server/src/cli.ts b/packages/mcp-server/src/cli.ts new file mode 100644 index 00000000000..dd95b5ca0ca --- /dev/null +++ b/packages/mcp-server/src/cli.ts @@ -0,0 +1,8 @@ +import { spawn } from 'node:child_process'; + +const MCP_SERVER_URL = 'https://remote-mcp-server-staging.colinclerk.workers.dev/mcp'; + +const args = ['-y', 'mcp-remote@latest', MCP_SERVER_URL, ...process.argv.slice(2)]; +const child = spawn('npx', args, { stdio: 'inherit' }); + +child.on('exit', code => process.exit(code ?? 0)); diff --git a/packages/mcp-server/tsconfig.json b/packages/mcp-server/tsconfig.json new file mode 100644 index 00000000000..675dd819dd5 --- /dev/null +++ b/packages/mcp-server/tsconfig.json @@ -0,0 +1,19 @@ +{ + "compilerOptions": { + "moduleResolution": "Bundler", + "module": "ESNext", + "sourceMap": false, + "strict": true, + "esModuleInterop": true, + "skipLibCheck": true, + "allowJs": true, + "target": "ES2022", + "emitDeclarationOnly": true, + "declaration": true, + "declarationMap": true, + "outDir": "dist", + "resolveJsonModule": true, + "declarationDir": "dist/types" + }, + "include": ["src"] +} diff --git a/packages/mcp-server/tsup.config.ts b/packages/mcp-server/tsup.config.ts new file mode 100644 index 00000000000..8becc7eb322 --- /dev/null +++ b/packages/mcp-server/tsup.config.ts @@ -0,0 +1,24 @@ +import { defineConfig } from 'tsup'; + +import { name, version } from './package.json'; + +export default defineConfig(overrideOptions => { + const isProd = overrideOptions.env?.NODE_ENV === 'production'; + + return { + entry: ['src/cli.ts'], + dts: false, + clean: true, + bundle: true, + sourcemap: true, + format: 'esm', + define: { + PACKAGE_NAME: `"${name}"`, + PACKAGE_VERSION: `"${version}"`, + __DEV__: `${!isProd}`, + }, + banner: { + js: '#!/usr/bin/env node', + }, + }; +}); diff --git a/pnpm-lock.yaml b/pnpm-lock.yaml index 4755c33c29d..733800c2d64 100644 --- a/pnpm-lock.yaml +++ b/pnpm-lock.yaml @@ -684,6 +684,8 @@ importers: specifier: workspace:^ version: link:../shared + packages/mcp-server: {} + packages/nextjs: dependencies: '@clerk/backend':