🔐 Clerk MCP Server

Servidor MCP (Model Context Protocol) para gerenciamento completo de usuários do Clerk. Este projeto permite que você integre facilmente as funcionalidades do Clerk com qualquer cliente MCP compatível, incluindo Cursor AI, Claude Desktop e VS Code.

✨ Funcionalidades

Este servidor MCP expõe 4 ferramentas essenciais para gerenciar usuários do Clerk:

🛠️ Ferramentas Disponíveis

Ferramenta	Descrição	Parâmetros
`list-users`	Lista usuários com paginação	`limit` (1-100), `offset` , `orderBy`
`delete-user`	Deleta permanentemente um usuário	`userId` (obrigatório)
`lock-user`	Bloqueia um usuário (impede login)	`userId` (obrigatório)
`unlock-user`	Desbloqueia um usuário (permite login)	`userId` (obrigatório)

⚠️ ATENÇÃO: A operação delete-user é irreversível! Use com muito cuidado.

🚀 Instalação Rápida

1. Clone o Repositório

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

2. Instale as Dependências

npm install

3. Configure as Variáveis de Ambiente

Opção A: Copie o arquivo de exemplo

cp env.example .env.local

Opção B: Crie manualmente o arquivo

# Clerk API Keys CLERK_SECRET_KEY=your_secret_key_here NEXT_PUBLIC_CLERK_PUBLISHABLE_KEY=your_publishable_key_here # Server Configuration PORT=5000

4. Obtenha suas Chaves do Clerk

Acesse Clerk Dashboard
Selecione seu projeto
Vá em API Keys
Copie:
- Secret Key (começa com sk_live_ ou sk_test_)
- Publishable Key (começa com pk_live_ ou pk_test_)

5. Compile o Projeto

npm run build

⚙️ Configuração por Cliente MCP

🎯 Cursor AI (Recomendado)

Abra as configurações do Cursor (Ctrl/Cmd + ,)
Procure por "MCP" na barra de pesquisa
Adicione a configuração:

{ "mcpServers": { "Clerk": { "command": "node", "args": ["caminho/para/mcp_clerk/dist/server-stdio.js"], "env": { "CLERK_SECRET_KEY": "your_secret_key_here", "NEXT_PUBLIC_CLERK_PUBLISHABLE_KEY": "your_publishable_key_here" } } } }

Exemplo com caminho completo:

{ "mcpServers": { "Clerk": { "command": "node", "args": ["C:\\projetos\\mcp_clerk\\dist\\server-stdio.js"], "env": { "CLERK_SECRET_KEY": "your_secret_key_here", "NEXT_PUBLIC_CLERK_PUBLISHABLE_KEY": "your_publishable_key_here" } } } }

Reinicie o Cursor
Teste: Digite @Clerk no chat para ver as ferramentas disponíveis

🤖 Claude Desktop

Abra o arquivo de configuração:
- Windows: %APPDATA%\Claude\claude_desktop_config.json
- macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
Adicione a configuração:

Reinicie o Claude Desktop

💻 VS Code

Instale a extensão MCP (se disponível)
Configure via settings.json:

{ "mcp.servers": { "Clerk": { "command": "node", "args": ["caminho/para/mcp_clerk/dist/server-stdio.js"], "env": { "CLERK_SECRET_KEY": "your_secret_key_here", "NEXT_PUBLIC_CLERK_PUBLISHABLE_KEY": "your_publishable_key_here" } } } }

🌐 Modo HTTP (Para Desenvolvimento)

Se preferir usar o servidor HTTP para testes:

1. Inicie o Servidor HTTP

npm start

2. Teste com MCP Inspector

npx @modelcontextprotocol/inspector

Conecte em: http://localhost:5000/mcp

3. Teste com cURL

Health Check:

curl http://localhost:5000

Listar Usuários:

curl -X POST http://localhost:5000/mcp \ -H "Content-Type: application/json" \ -d '{ "jsonrpc": "2.0", "method": "tools/call", "params": { "name": "list-users", "arguments": { "limit": 10, "offset": 0 } }, "id": 1 }'

Bloquear Usuário:

curl -X POST http://localhost:5000/mcp \ -H "Content-Type: application/json" \ -d '{ "jsonrpc": "2.0", "method": "tools/call", "params": { "name": "lock-user", "arguments": { "userId": "user_xxxxxxxxxxxxx" } }, "id": 2 }'

📚 Exemplos de Uso

No Cursor AI

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

No Claude Desktop

Use a ferramenta Clerk para listar os últimos 10 usuários cadastrados Bloqueie o usuário com ID user_2abc123def456

🔧 Scripts Disponíveis

# Desenvolvimento npm run dev # Servidor HTTP em modo dev npm run dev:stdio # Servidor STDIO em modo dev # Produção npm run build # Compila o projeto npm start # Servidor HTTP (porta 5000) npm run start:stdio # Servidor STDIO

📁 Estrutura do Projeto

mcp_clerk/ ├── src/ │ ├── server.ts # Servidor HTTP (porta 5000) │ ├── server-stdio.ts # Servidor STDIO (para Cursor/VS Code) │ └── clerk-tools.ts # Implementação das ferramentas ├── dist/ # Arquivos compilados ├── env.example # Exemplo de configuração ├── .env.local # Suas credenciais (NÃO commitado) ├── .gitignore # Arquivos ignorados pelo Git ├── package.json # Dependências e scripts ├── tsconfig.json # Configuração TypeScript └── README.md # Este arquivo

🛡️ Segurança

✅ Nenhuma chave hardcoded no código
✅ Arquivo pelo .gitignore
✅ Variáveis de ambiente carregadas via dotenv
⚠️ Nunca compartilhe suas credenciais do Clerk
⚠️ Operação - use com cuidado!

🐛 Troubleshooting

Problema: "CLERK_SECRET_KEY não encontrada"

Solução: Verifique se o arquivo .env.local existe e contém a chave correta.

Problema: "Erro ao conectar com Clerk"

Solução: Verifique se suas chaves do Clerk estão corretas e ativas.

Problema: "Ferramentas não aparecem no Cursor"

Solução:

Verifique o caminho no arquivo de configuração
Reinicie o Cursor completamente
Verifique se o projeto foi compilado (npm run build)

Problema: "Porta 5000 já está em uso"

Solução: Altere a porta no arquivo .env.local:

PORT=3001

🤝 Contribuindo

Fork o projeto
Crie uma branch para sua feature (git checkout -b feature/AmazingFeature)
Commit suas mudanças (git commit -m 'Add some AmazingFeature')
Push para a branch (git push origin feature/AmazingFeature)
Abra um Pull Request

📄 Licença

Este projeto está sob a licença MIT. Veja o arquivo LICENSE para mais detalhes.

🙏 Agradecimentos

Clerk - Autenticação e gerenciamento de usuários
Model Context Protocol - Protocolo para integração com IAs
Cursor AI - Editor de código com IA integrada

Feito com ❤️ para a comunidade de desenvolvedores

Clerk MCP Server