MongoDB MCP Server

Um servidor MCP que fornece ferramentas e prompts para interagir com

Documentação

Servidor MCP MongoDB

Um servidor robusto de Model Context Protocol (MCP) que fornece ferramentas e prompts para interagir com um banco de dados MongoDB. Construído com Node.js e MongoDB, com tratamento de desligamento gracioso e gerenciamento abrangente de erros.

Recursos

Integração com MongoDB usando Mongoose
Ferramentas de gerenciamento de usuários:
- create-user: Criar um novo usuário
- get-user: Recuperar usuário por e-mail
- list-users: Listar todos os usuários com paginação
Prompts interativos para operações guiadas
Tratamento de desligamento gracioso
Gerenciamento abrangente de erros
Implementação limpa em arquivo único

Pré-requisitos

Node.js (versão LTS mais recente)
MongoDB (v8.0 ou superior)
Claude for Desktop (versão mais recente)
Visual Studio Code com extensão Cursor (para desenvolvimento)

Configuração de Desenvolvimento

Instale o MongoDB:

# Using Homebrew on macOS
brew tap mongodb/brew
brew install mongodb-community

# Start MongoDB service
brew services start mongodb-community

Instale o Cursor no VS Code:
- Abra o VS Code
- Vá para Extensões (Ctrl+Shift+X)
- Pesquise por "Cursor"
- Clique em Instalar

Clone e Configure:

git clone <repository-url>
cd learn-mcp-mongo
npm install

Configure o Ambiente:

cp .env.example .env
# Edit .env with your MongoDB URI if different from default

Início Rápido

Clone ou baixe este repositório
Instale as dependências:
```
npm install
```
Configure o MongoDB:
- Certifique-se de que o MongoDB esteja rodando localmente (padrão: mongodb://localhost:27017)
- Ou atualize o arquivo .env com sua string de conexão do MongoDB:
```
MONGODB_URI=your_mongodb_connection_string
```
Configure o Claude for Desktop:
- Abra ou crie ~/Library/Application Support/Claude/claude_desktop_config.json
- Adicione a seguinte configuração:
```
{
  "mcpServers": {
    "mcp-mongo": {
      "command": "node",
      "args": ["/absolute/path/to/server.js"]
    }
  }
}
```
Inicie o Claude for Desktop
- O servidor MCP iniciará automaticamente
- Procure pelo ícone "Search and tools" para acessar as ferramentas

Usando o Cursor com o Servidor MCP

Instale o Cursor (Editor de Código com IA):
- Baixe de https://www.cursor.so/
- Instale e abra o Cursor na sua máquina
Adicione o Servidor MCP ao Cursor:
- Abra o Cursor
- Vá para Settings > Integrations > MCP Servers
- Clique em Add MCP Server
- Preencha:
  - Nome: mcp-mongo
  - Comando: node
  - Argumentos: /absolute/path/to/server.js
  - Diretório de Trabalho: /absolute/path/to/learn-mcp-mongo
- Salve e ative a integração
Use os Recursos de IA do Cursor:
- Abra a pasta do seu projeto no Cursor
- Use /help na paleta de comandos para ver os comandos de IA disponíveis
- Use /edit, /fix, /doc e outros recursos de IA para interagir com seu código e ferramentas MCP
- Agora você pode testar, depurar e desenvolver seu servidor MCP diretamente no Cursor com assistência de IA

Exemplos de Uso

Criando um Usuário

Create a new user with:
- name: "John Doe"
- email: "john@example.com"
- age: 30

Encontrando um Usuário

Get user information for email: john@example.com

Estrutura do Projeto

learn-mcp-mongo/
├── server.js     # Main server file with all functionality
├── .env          # Environment variables
└── package.json  # Project dependencies and scripts

Ferramentas Disponíveis

create-user

Cria um novo usuário no banco de dados.

Parâmetros:
- name: Nome completo do usuário (string, obrigatório)
- email: Endereço de e-mail do usuário (string, obrigatório, único)
- age: Idade do usuário (número, obrigatório)

Resposta:

{
  "_id": "user_id",
  "name": "John Doe",
  "email": "john@example.com",
  "age": 30,
  "createdAt": "2025-06-26T00:00:00.000Z"
}

get-user

Recupera um usuário pelo seu endereço de e-mail.

Parâmetros:
- email: Endereço de e-mail do usuário (string, obrigatório)

Resposta:

{
  "_id": "user_id",
  "name": "John Doe",
  "email": "john@example.com",
  "age": 30,
  "createdAt": "2025-06-26T00:00:00.000Z"
}

list-users

Lista todos os usuários no banco de dados com paginação.

Parâmetros:
- limit: Número máximo de usuários a retornar (número, opcional, padrão: 10)

Resposta:

[
  {
    "_id": "user_id",
    "name": "John Doe",
    "email": "john@example.com",
    "age": 30,
    "createdAt": "2025-06-26T00:00:00.000Z"
  },
  // ... more users
]

Prompts Disponíveis

create-new-user

Um prompt interativo que guia você pelo processo de criação de um novo usuário, solicitando:

Nome Completo
Endereço de E-mail
Idade

Guia de Desenvolvimento

Executando o Servidor

Inicie no Modo de Desenvolvimento:

# Run with inspector for debugging
npx @modelcontextprotocol/inspector node mcp-server.js

# Or run directly
npm start

Usando o Cursor no VS Code:
- Abra o projeto no VS Code
- Use os recursos de IA do Cursor:
  - Digite /help para comandos do Cursor
  - Use /edit para sugestões de código
  - Use /doc para gerar documentação
  - Use /fix para obter correções de erros

Depuração

Verifique os Logs do Servidor:

# Watch server logs in real-time
tail -f ~/Library/Logs/Claude/mcp*.log

Operações do MongoDB:

# Check MongoDB status
mongosh
use mcp-mongo
db.users.find()  # List all users

Teste as Ferramentas Manualmente:

# Using curl to test tools (when running in HTTP mode)
curl -X POST http://localhost:3000/tools/list-users

Recursos do Servidor

Desligamento Gracioso:
- Trata sinais SIGINT, SIGTERM, SIGHUP
- Fecha conexões do MongoDB corretamente
- Registra o processo de desligamento
Tratamento de Erros:
- Erros de conexão com o MongoDB
- Erros de execução de ferramentas
- Exceções não capturadas
- Rejeições não tratadas
Opções de Desempenho:
- Timeout de conexão do MongoDB: 5s
- Frequência de heartbeat: 2s
- Paginação na listagem de usuários

Solução de Problemas

Certifique-se de que o MongoDB esteja rodando e acessível
Verifique os logs do Claude for Desktop em ~/Library/Logs/Claude/mcp*.log
Verifique se o caminho do server.js em claude_desktop_config.json está correto
Reinicie o Claude for Desktop após alterações na configuração