🔐 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 .env.local

# 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

1. Acesse Clerk Dashboard
2. Selecione seu projeto
3. Vá em API Keys
4. 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)

1. Abra as configurações do Cursor (Ctrl/Cmd + ,)
2. Procure por "MCP" na barra de pesquisa
3. 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"
      }
    }
  }
}

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

🤖 Claude Desktop

1. Abra o arquivo de configuração:

   • Windows: %APPDATA%\Claude\claude_desktop_config.json
   • macOS: ~/Library/Application Support/Claude/claude_desktop_config.json

2. 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"
      }
    }
  }
}

3. Reinicie o Claude Desktop

💻 VS Code

1. Instale a extensão MCP (se disponível)
2. 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 .env.local protegido pelo .gitignore
• ✅ Variáveis de ambiente carregadas via dotenv
• ⚠️ Nunca compartilhe suas credenciais do Clerk
• ⚠️ Operação delete-user é irreversível - 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:

1. Verifique o caminho no arquivo de configuração
2. Reinicie o Cursor completamente
3. 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

1. Fork o projeto
2. Crie uma branch para sua feature (git checkout -b feature/AmazingFeature)
3. Commit suas mudanças (git commit -m 'Add some AmazingFeature')
4. Push para a branch (git push origin feature/AmazingFeature)
5. 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