Clerk MCP Server

A comprehensive Model Context Protocol (MCP) server for Clerk authentication and user management. This server provides complete access to the Clerk Backend API through organized tools for AI assistants and applications.

Features

🔐 User Management

• Create, update, delete users
• User authentication and verification
• Profile management and metadata
• Ban/unban and lock/unlock users
• OAuth token management

🏢 Organization Management

• Create and manage organizations
• Organization metadata and logo management
• Member role management
• Organization invitations

🔗 Session & Client Management

• Session tracking and management
• Client verification
• JWT token creation from templates
• Session revocation

📧 Invitation System

• Individual and bulk invitations
• Invitation status tracking
• Invitation revocation

🔒 Security Controls

• Allowlist and blocklist management
• Webhook endpoint management
• Domain verification
• Sign-in token generation

⚙️ Configuration

• JWT template management
• Custom domain setup
• Redirect URL management

Installation

1. Clone or create the project:

mkdir clerk-mcp && cd clerk-mcp

2. Install dependencies:

npm install

3. Build the project:

npm run build

Configuration

Multi-Project Support

This MCP server supports managing multiple Clerk applications from a single server instance. Configure multiple projects in your MCP settings:

{
  "mcpServers": {
    "clerk": {
      "command": "node",
      "args": ["path/to/clerk-mcp/dist/index.js"],
      "env": {
        "CLERK_PROJECTS": "{\"production\":{\"apiKey\":\"sk_live_...\",\"name\":\"Production App\"},\"staging\":{\"apiKey\":\"sk_test_...\",\"name\":\"Staging App\"}}"
      }
    }
  }
}

Or configure via Smithery.ai config:

projects:
  production:
    apiKey: "sk_live_your_production_key"
    name: "Production App"
  staging:
    apiKey: "sk_test_your_staging_key"
    name: "Staging App"
  development:
    apiKey: "sk_test_your_dev_key"
    name: "Development App"

Single Project Configuration

For a single project, you can configure it like this:

projects:
  main:
    apiKey: "sk_test_your_clerk_secret_key_here"

Tools Available

Users Tool

Comprehensive user management with operations:

• list - List users with filtering options
• create - Create new users
• get - Get user details
• update - Update user information
• delete - Delete users
• ban/unban - Ban/unban users
• lock/unlock - Lock/unlock users
• updateMetadata - Update user metadata
• verifyPassword - Verify user passwords
• getOAuthAccessToken - Get OAuth tokens
• disableMfa - Disable MFA for users

Organizations Tool

Organization management with operations:

• list - List organizations
• create - Create organizations
• get - Get organization details
• update - Update organizations
• delete - Delete organizations
• mergeMetadata - Update organization metadata
• uploadLogo - Upload organization logos
• deleteLogo - Delete organization logos

Sessions Tool

Session management with operations:

• list - List sessions
• get - Get session details
• revoke - Revoke sessions
• createTokenFromTemplate - Create JWT tokens

Invitations Tool

Invitation management with operations:

• list - List invitations
• create - Create invitations
• bulkCreate - Create multiple invitations
• revoke - Revoke invitations

Organization Memberships Tool

Member management with operations:

• list - List organization members
• create - Add members to organizations
• update - Update member roles
• delete - Remove members
• updateMetadata - Update member metadata

Additional Tools

• Clients: Client device management
• Webhooks: Webhook endpoint management
• JWT Templates: Custom JWT template management
• Domains: Custom domain management
• Blocklist/Allowlist: Security controls
• Redirect URLs: Allowed redirect management
• Sign-in Tokens: Passwordless authentication

Example Usage

All operations require a project_id parameter to specify which Clerk project to use.

Create a User

{
  "tool": "users",
  "arguments": {
    "project_id": "production",
    "operation": "create",
    "createUserData": {
      "email_address": ["user@example.com"],
      "password": "secure_password",
      "first_name": "John",
      "last_name": "Doe"
    }
  }
}

List Organizations

{
  "tool": "organizations",
  "arguments": {
    "project_id": "staging",
    "operation": "list",
    "limit": 10,
    "include_members_count": true
  }
}

Add User to Organization

{
  "tool": "organization_memberships",
  "arguments": {
    "project_id": "production",
    "operation": "create",
    "organization_id": "org_123",
    "user_id": "user_456",
    "role": "org:member"
  }
}

Managing Multiple Projects

You can easily switch between projects by changing the project_id:

{
  "tool": "users",
  "arguments": {
    "project_id": "development",
    "operation": "list",
    "limit": 20
  }
}

Smithery.ai Deployment

This MCP server is designed to work with Smithery.ai. Use the included smithery.yaml configuration file for deployment.

API Reference

This server implements the complete Clerk Backend API. For detailed parameter information, refer to the Clerk API documentation.

Error Handling

The server provides comprehensive error handling with:

• Proper HTTP status code mapping
• Detailed error messages from Clerk API
• Graceful fallbacks for common issues
• Authentication error detection

Contributing

1. Fork the repository
2. Create a feature branch
3. Make your changes
4. Test thoroughly
5. Submit a pull request

License

MIT License - see LICENSE file for details.

Support

For issues and questions:

• Check the Clerk documentation
• Review the error messages in the server logs
• Ensure your API key has proper permissions
• Verify your Clerk instance configuration