Clerk

You set up this MCP server to manage Clerk users through any MCP-compatible client, giving you a centralized way to list, lock, unlock, and delete users with secure key-based access.

How to use

• Connect your MCP client to the Clerk server using the HTTP endpoint or the local STDIO endpoint. The HTTP path you’ll test is the /mcp route served on the server, while the STDIO setup runs as a local process that exposes tools to your editor or IDE.

How to install

Prerequisites: you need Node.js and npm installed on your system.

1. Clone the project and enter the directory.

git clone https://github.com/correaito/mcp_clerk.git
cd mcp_clerk

2. Install dependencies.

npm install

3. Configure environment variables.

# Option A: Copy example and customize
cp env.example .env.local

# Option B: Create manually
# Clerk API Keys
CLERK_SECRET_KEY=your_secret_key_here
NEXT_PUBLIC_CLERK_PUBLISHABLE_KEY=your_publishable_key_here

# Server Configuration
PORT=5000

4. Obtain your Clerk API keys from the Clerk Dashboard under API Keys.

5. Build the project.

npm run build

6. Run in HTTP mode for development or testing.

npm start

7. If you want to use the STDIO-based flow with editors like Cursor AI, Claude Desktop, or VS Code, use the STDIO commands shown in the configuration examples.

Additional configuration and usage notes

The server exposes four essential tools to manage Clerk users: list-users (paginated), delete-user (irreversible), lock-user, and unlock-user. Use these tools from your MCP client to perform common user management tasks.

Example tool behavior you can expect when connected through an MCP client:

• List users with pagination and sorting options
• Permanently delete a user with clear confirmation
• Lock a user to prevent login and later unlock when needed

Security and best practices

• Do not hardcode API keys in your codebase. Store keys in environment variables and protect the local .env.local file.

• Be aware that delete-user is irreversible. Use it only when you are certain you want to permanently remove a user.

• Limit access to the server and rotate keys periodically through your Clerk dashboard.

Troubleshooting

• If the Clerk secret key cannot be found, verify that .env.local exists and contains CLERK_SECRET_KEY.

• If tools do not appear in your MCP client, ensure the server was compiled and started, and that you use the correct path to the server-stdio.js file in your STDIO configuration.

• If port conflicts occur, change PORT in the environment configuration and restart the server.

Usage examples for common MCP clients

Cursor AI and other editors can expose the Clerk tools as commands you can invoke from the chat or command palette. The following patterns show how you typically invoke the tools once the client is connected to Clerk via MCP.

@Clerk list-users limit=5
@Clerk lock-user userId=user_2abc123def456
@Clerk unlock-user userId=user_2abc123def456

Scripts available

Development tasks and runtime options are organized as follows.

{
  "scripts": {
    "dev": "npm run start:dev",
    "dev:stdio": "npm run start:stdio",
    "build": "npm run build",
    "start": "npm run start:http",
    "start:stdio": "node dist/server-stdio.js"
  }
}

Available tools

list-users

Lists Clerk users with pagination support via limit, offset, and orderBy parameters.

delete-user

Permanently deletes a user identified by userId. Irreversible operation.

lock-user

Locks a user to prevent login until unlocked.

unlock-user

Unlocks a previously locked user to restore login capability.