MongoDB

Interaja com bancos de dados MongoDB usando linguagem natural. Consulte coleções, inspecione esquemas e gerencie dados.

GitHub
15
Experimente este MCPPatrocinado

Documentação

🗄️ Servidor MCP MongoDB para LLMS

Node.js 18+ License: MIT npm version smithery badge

Um servidor Model Context Protocol (MCP) que permite que LLMs interajam diretamente com bancos de dados MongoDB. Consulte coleções, inspecione esquemas e gerencie dados de forma integrada por meio de linguagem natural.

📚 O que é Model Context Protocol (MCP)?

O Model Context Protocol (MCP) é um padrão aberto desenvolvido pela Anthropic que cria uma forma universal de sistemas de IA se conectarem a fontes de dados e ferramentas externas. O MCP estabelece um canal de comunicação padronizado entre:

  • Clientes MCP: Assistentes de IA como Claude que consomem dados (ex.: Claude Desktop, Cursor.ai)
  • Servidores MCP: Serviços que expõem dados e funcionalidades (como este servidor MongoDB)

Principais benefícios do MCP:

  • Acesso Universal: Fornece um protocolo único para assistentes de IA consultarem dados de diversas fontes
  • Conexões Padronizadas: Gerencia autenticação, políticas de uso e formatos de dados de forma consistente
  • Ecossistema Sustentável: Promove conectores reutilizáveis que funcionam em múltiplos clientes LLM

✨ Recursos

  • 🔍 Inspeção de esquema de coleções
  • 📊 Consulta e filtragem de documentos
  • 📈 Gerenciamento de índices
  • 📝 Operações com documentos (inserir, atualizar, excluir)
  • 🔒 Acesso seguro ao banco de dados por meio de strings de conexão
  • 📋 Tratamento abrangente de erros e validação

📋 Pré-requisitos

Antes de começar, certifique-se de ter:

Você pode verificar sua instalação do Node.js executando:

node --version  # Should show v18.0.0 or higher

🚀 Início Rápido

Para começar, encontre sua URL de conexão do MongoDB e adicione esta configuração ao arquivo de configuração do Claude Desktop:

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

{
  "mcpServers": {
    "mongodb": {
      "command": "npx",
      "args": [
        "mongo-mcp",
        "mongodb://<username>:<password>@<host>:<port>/<database>?authSource=admin"
      ]
    }
  }
}

Instalação via Smithery

Smithery.ai é uma plataforma de registro para servidores MCP que simplifica a descoberta e instalação. Para instalar o MongoDB MCP Server para Claude Desktop automaticamente via Smithery:

npx -y @smithery/cli install mongo-mcp --client claude

Integração com Cursor.ai

Para usar MongoDB MCP com Cursor.ai:

  1. Abra o Cursor.ai e navegue até Settings > Features
  2. Procure por "MCP Servers" no painel de recursos
  3. Adicione um novo servidor MCP com a seguinte configuração:
    • Nome: mongodb
    • Comando: npx
    • Argumentos: mongo-mcp mongodb://<username>:<password>@<host>:<port>/<database>?authSource=admin

Nota: O Cursor atualmente suporta ferramentas MCP apenas no recurso Agent in Composer.

Configuração do Sandbox de Teste

Se você não tiver um servidor MongoDB para conectar e quiser criar um sandbox de exemplo, siga estes passos:

  1. Inicie o MongoDB usando Docker Compose:
docker-compose up -d
  1. Popule o banco de dados com dados de teste:
npm run seed

Configurar Claude Desktop

Adicione esta configuração ao arquivo de configuração do Claude Desktop:

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

Modo de Desenvolvimento Local:

{
  "mcpServers": {
    "mongodb": {
      "command": "node",
      "args": [
        "dist/index.js",
        "mongodb://root:example@localhost:27017/test?authSource=admin"
      ]
    }
  }
}

Estrutura de Dados do Sandbox de Teste

O script de seed cria três coleções com dados de exemplo:

Usuários

  • Informações pessoais (nome, email, idade)
  • Endereço aninhado com coordenadas
  • Matrizes de interesses
  • Datas de associação

Produtos

  • Detalhes do produto (nome, SKU, categoria)
  • Especificações aninhadas
  • Informações de preço e estoque
  • Tags e avaliações

Pedidos

  • Detalhes do pedido com itens
  • Referências de usuário
  • Informações de envio e pagamento
  • Rastreamento de status

🎯 Exemplos de Prompts

Experimente estes prompts com Claude para explorar a funcionalidade:

Operações Básicas

"What collections are available in the database?"
"Show me the schema for the users collection"
"Find all users in San Francisco"

Consultas Avançadas

"Find all electronics products that are in stock and cost less than $1000"
"Show me all orders from the user john@example.com"
"List the products with ratings above 4.5"

Gerenciamento de Índices

"What indexes exist on the users collection?"
"Create an index on the products collection for the 'category' field"
"List all indexes across all collections"

Operações com Documentos

"Insert a new product with name 'Gaming Laptop' in the products collection"
"Update the status of order with ID X to 'shipped'"
"Find and delete all products that are out of stock"

📝 Ferramentas Disponíveis

O servidor fornece estas ferramentas para interação com o banco de dados:

Ferramentas de Consulta

  • listCollections: Lista as coleções disponíveis no banco de dados
  • find: Consulta documentos com filtragem e projeção
  • insertOne: Insere um único documento em uma coleção
  • updateOne: Atualiza um único documento em uma coleção
  • deleteOne: Exclui um único documento de uma coleção

Ferramentas de Índice

  • createIndex: Cria um novo índice em uma coleção
  • dropIndex: Remove um índice de uma coleção
  • indexes: Lista índices de uma coleção

🛠️ Desenvolvimento

Este projeto é construído com:

  • TypeScript para desenvolvimento com segurança de tipos
  • Driver Node.js do MongoDB para operações de banco de dados
  • Zod para validação de esquema
  • Model Context Protocol SDK para implementação do servidor

Para configurar o ambiente de desenvolvimento:

# Install dependencies
npm install

# Build the project
npm run build

# Run in development mode
npm run dev

# Run tests
npm test

🔒 Considerações de Segurança

Ao usar este servidor MCP com seu banco de dados MongoDB:

  1. Crie um usuário MongoDB dedicado com as permissões mínimas necessárias para seu caso de uso
  2. Nunca use credenciais de administrador em ambientes de produção
  3. Ative o registro de acesso para fins de auditoria
  4. Defina permissões de leitura/escrita apropriadas nas coleções
  5. Use parâmetros da string de conexão para restringir o acesso (ex.: readPreference=secondary)
  6. Considere a lista de permissões de IP para restringir o acesso ao banco de dados

⚠️ IMPORTANTE: Sempre siga o princípio do menor privilégio ao configurar o acesso ao banco de dados.

🌐 Como Funciona

O servidor MongoDB MCP:

  1. Conecta-se ao seu banco de dados MongoDB usando a string de conexão fornecida
  2. Expõe operações do MongoDB como ferramentas que seguem a especificação MCP
  3. Valida entradas usando Zod para segurança de tipos e proteção
  4. Executa consultas e retorna dados estruturados ao cliente LLM
  5. Gerencia pool de conexões e tratamento adequado de erros

Todas as operações são executadas com validação adequada para prevenir problemas de segurança, como ataques de injeção.

📦 Implantação

Você pode implantar este servidor MCP de várias formas:

  • Localmente via npx (como mostrado no Início Rápido)
  • Como pacote npm global: npm install -g @coderay/mongo-mcp-server
  • Em um contêiner Docker (veja o Dockerfile no repositório)
  • Como serviço em plataformas como Heroku, Vercel ou AWS

❓ Solução de Problemas

Problemas Comuns

  1. Erros de Conexão

    • Verifique se sua string de conexão do MongoDB está correta
    • Confirme se o servidor MongoDB está em execução e acessível
    • Garanta que as permissões de rede permitam a conexão

  2. Problemas de Autenticação

    • Confirme se o nome de usuário e a senha estão corretos
    • Verifique se o banco de dados de autenticação está especificado (geralmente authSource=admin)
    • Verifique se o MongoDB requer conexões TLS/SSL

  3. Problemas na Execução de Ferramentas

    • Reinicie completamente o Claude Desktop ou Cursor.ai
    • Verifique os logs para mensagens de erro detalhadas: 
      # macOS
tail -n 20 -f ~/Library/Logs/Claude/mcp*.log

  4. Problemas de Desempenho

    • Considere adicionar índices apropriados aos campos consultados com frequência
    • Use projeção para limitar os dados retornados nas consultas
    • Use parâmetros de limite e deslocamento para paginação

Obtendo Ajuda

Se você encontrar problemas:

🤝 Contribuições

Contribuições são bem-vindas! Sinta-se à vontade para enviar um Pull Request.

  1. Faça um fork do repositório
  2. Crie sua branch de recurso (git checkout -b feature/amazing-feature)
  3. Faça commit das suas alterações (git commit -m 'Add some amazing feature')
  4. Envie para a branch (git push origin feature/amazing-feature)
  5. Abra um Pull Request

📜 Licença

Este projeto é licenciado sob a Licença MIT - veja o arquivo LICENSE para detalhes.