Clerk

You can run a dedicated MCP server to query and manage your Clerk organizations, members, users, roles, and metadata from AI assistants and tooling. This server supports secure, flexible access patterns and lets you choose between hosting a single Clerk secret on the server or passing keys per request, making it suitable for personal use, internal teams, or multi-tenant deployments.

How to use

Connect your preferred MCP client to the Clerk MCP Server endpoint to start querying and managing Clerk data. You can operate in either Hosted mode, where the server stores and uses a single Clerk secret key, or Public mode, where each request carries its own key. Once connected, you can list organizations, inspect members, manage invitations, and retrieve user details through the available MCP tools. Use the health check endpoint to verify the server is reachable and report mode/connection status.

Choose the mode that matches your deployment needs. Hosted mode is simpler to configure and ideal for personal or internal deployments. Public mode supports multi-tenant setups by passing the Clerk key with every request, keeping the key off the server.

How to install

Prerequisites: you need Node.js installed on your machine. You will also need an active Clerk account to obtain an API key for development and production use.

Step-by-step setup and run flow from a clean environment.

# 1. Clone the project
git clone https://github.com/BalajiSriraman/Clerk-MCP.git
cd Clerk-MCP

# 2. Install dependencies
npm install

# 3. Prepare for Hosted mode by copying the example env file
cp .env.example .env
# Edit .env and paste your Clerk Secret Key:
# CLERK_SECRET_KEY=sk_test_xxxxxxxxxxxxxxxxxxxxxxxxxxxxx

# 4. Start in Hosted mode
npm run dev

If you prefer Public mode (per-request keys) you do not need to place a secret on the server. Start the server with the same command and supply keys per request via the client configurations.

Your MCP endpoint will be available at the default server URL path once the server starts.

Configuration and usage notes

Security and best practices: Never commit your secret keys to version control. In Hosted mode, place the Clerk secret in a server environment variable (for example, CLERK_SECRET_KEY). In Public mode, keys are supplied by clients in the X-Clerk-Secret-Key header for every request.

Health check and status: You can verify connectivity and mode by hitting the health endpoint. Hosted mode returns status ok with mode hosted and clerkConnected true, while Public mode returns status ok with mode public and clerkConnected null.

Tools and capabilities overview

The server exposes tools to manage Clerk organizations, members, invitations, and users. You can list, get, create, update, and delete resources as described in the tool references.

Examples of common tasks

List all organizations and inspect their member counts.

Create a new organization named Design Team with slug design-team and add public metadata.

Show all pending invitations for a specific organization.

Find users by email domain and update a user’s public metadata to reflect a plan change.

Notes on production deployment

To run in production, build the Nuxt/Node.js app and serve it with your preferred hosting platform. You can also deploy via Docker. If you self-host, use your own deployment URL in client configurations instead of the example URL.

Available tools

clerk_list_organizations

List organizations with optional filtering by name/slug, pagination, and member counts

clerk_get_organization

Retrieve details for a specific organization including metadata and timestamps

clerk_create_organization

Create a new organization with a name, slug, and metadata

clerk_update_organization_metadata

Update an organization’s public/private metadata

clerk_delete_organization

Delete an organization permanently

clerk_list_organization_members

List members of an organization with roles, user data, and metadata

clerk_update_member_role

Change a member's role within an organization (e.g. org:admin, org:member)

clerk_update_member_metadata

Update membership metadata (public/private)

clerk_remove_member

Remove a member from an organization

clerk_list_organization_invitations

List invitations by status (pending/accepted/revoked)

clerk_create_invitation

Invite a user to an organization by email

clerk_list_users

List all instance users with search by name/email/phone

clerk_get_user

Get full user profile including emails, phones, and metadata

clerk_update_user_metadata

Update user public/private/unsafe metadata