clerk-mcp-server

apigene/clerk-mcp-server

3.1

If you are the rightful owner of clerk-mcp-server and would like to certify it and/or have it hosted online, please leave a comment on the right or send an email to dayong@mcphub.com.

This is a sample Next.js application that demonstrates how to build a Model Context Protocol (MCP) server with Clerk authentication.

Tools
1
Resources
0
Prompts
0

Clerk MCP Server

A sample Next.js application that demonstrates how to build an MCP (Model Context Protocol) server with Clerk authentication.

Features

  • 🔐 Secure MCP server with Clerk OAuth authentication
  • 🛠️ Example tool: get-clerk-user-data that retrieves authenticated user information
  • 📡 Support for both HTTP and SSE transport protocols
  • 🏗️ Built with Next.js 14 and TypeScript
  • 📋 OAuth metadata endpoints for MCP compliance

Prerequisites

  • Node.js 18+
  • A Clerk account (sign up at clerk.com)

Setup

  1. Clone and install dependencies:

    npm install

  2. Set up Clerk:

    • Go to your Clerk Dashboard
    • Create a new application or use an existing one
    • Copy your publishable key and secret key

  3. Configure environment variables:

    cp env.example .env.local

    Then edit .env.local and add your Clerk keys:

    NEXT_PUBLIC_CLERK_PUBLISHABLE_KEY=pk_test_your_publishable_key_here
CLERK_SECRET_KEY=sk_test_your_secret_key_here

  4. Run the development server:

    npm run dev

  5. Open your browser: Navigate to http://localhost:3000

MCP Server Endpoints

The MCP server is available at the following endpoints:

  • HTTP Transport: http://localhost:3000/mcp
  • SSE Transport: http://localhost:3000/sse

OAuth Metadata Endpoints

The server exposes the required OAuth metadata endpoints:

  • Authorization Server Metadata: http://localhost:3000/.well-known/oauth-authorization-server
  • Protected Resource Metadata: http://localhost:3000/.well-known/oauth-protected-resource/mcp

Available Tools

get-clerk-user-data

Retrieves information about the authenticated Clerk user.

Parameters: None

Returns: JSON string containing user data

Example Response:

{
  "id": "user_123",
  "emailAddresses": [...],
  "firstName": "John",
  "lastName": "Doe",
  ...
}

Project Structure

clerk-mcp-server/
├── app/
│   ├── [transport]/
│   │   └── route.ts              # MCP server implementation
│   ├── .well-known/
│   │   ├── oauth-authorization-server/
│   │   │   └── route.ts          # OAuth server metadata
│   │   └── oauth-protected-resource/
│   │       └── mcp/
│   │           └── route.ts      # Protected resource metadata
│   ├── layout.tsx                # Root layout
│   ├── page.tsx                  # Home page
│   └── globals.css               # Global styles
├── middleware.ts                 # Clerk middleware
├── package.json                  # Dependencies
├── next.config.js               # Next.js config
├── tsconfig.json                # TypeScript config
├── env.example                  # Environment variables template
└── README.md                    # This file

Adding Custom Tools

To add your own MCP tools, modify the app/[transport]/route.ts file:

server.tool(
  'your-tool-name',
  'Description of what your tool does',
  {
    // Define your tool parameters here
    paramName: {
      type: 'string',
      description: 'Parameter description'
    }
  },
  async (params, { authInfo }) => {
    // Your tool implementation
    const userId = authInfo!.extra!.userId! as string
    
    // Your logic here...
    
    return {
      content: [{ type: 'text', text: 'Your response' }],
    }
  },
)

Testing with MCP Clients

You can test the MCP server with any MCP-compatible client. The server supports:

  • OAuth 2.0 authentication with Clerk
  • HTTP and SSE transport protocols
  • Standard MCP tool invocation

Deployment

This project can be deployed to Vercel, Netlify, or any other Next.js-compatible hosting platform. Make sure to:

  1. Set the environment variables in your hosting platform
  2. Configure your Clerk application's allowed origins
  3. Update OAuth redirect URLs if needed

Learn More

License

MIT