README.md•7.67 kB
# 🔐 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
```bash
git clone https://github.com/correaito/mcp_clerk.git
cd mcp_clerk
```
### 2. Instale as Dependências
```bash
npm install
```
### 3. Configure as Variáveis de Ambiente
**Opção A: Copie o arquivo de exemplo**
```bash
cp env.example .env.local
```
**Opção B: Crie manualmente o arquivo `.env.local`**
```bash
# 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](https://dashboard.clerk.com/)
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
```bash
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**:
```json
{
"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:**
```json
{
"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**:
```json
{
"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**:
```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
```bash
npm start
```
### 2. Teste com MCP Inspector
```bash
npx @modelcontextprotocol/inspector
```
- Conecte em: `http://localhost:5000/mcp`
### 3. Teste com cURL
**Health Check:**
```bash
curl http://localhost:5000
```
**Listar Usuários:**
```bash
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:**
```bash
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
```bash
# 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](https://clerk.com/) - Autenticação e gerenciamento de usuários
- [Model Context Protocol](https://modelcontextprotocol.io/) - Protocolo para integração com IAs
- [Cursor AI](https://cursor.sh/) - Editor de código com IA integrada
---
**Feito com ❤️ para a comunidade de desenvolvedores**