MongoDB That Works

MongoDB That Works: Um servidor MongoDB MCP com descoberta de esquema e validação de campo. Requer uma variável de ambiente MONGODB_URI.

GitHub
1
Experimente este MCPPatrocinado

Documentação

MongoDB MCP That Works

npm version npm downloads npm weekly downloads CI GitHub release license GitHub stars node

Um servidor MongoDB MCP (Model Context Protocol) confiável, com descoberta de esquema integrada e validação de campos. É um servidor MCP padrão via stdio, então ele se conecta a qualquer cliente MCP — Claude Desktop, Claude Code, OpenAI Codex, Cursor, VS Code / GitHub Copilot, Zed e outros.

Publicado no npm: @sourabhshegane/mongodb-mcp-that-works · Instale com npx -y @sourabhshegane/mongodb-mcp-that-works

[!CAUTION] Este servidor se conecta ao seu MongoDB com acesso total de leitura/escrita para qualquer usuário e banco de dados que você fornecer via MONGODB_URI, e ele expõe ferramentas de escrita (insertOne, updateOne, deleteOne) para qualquer cliente conectado. Registre-o apenas com clientes MCP em que você confia. Para ambientes de alto risco, use um usuário MongoDB somente leitura ou um banco de dados dedicado.

Recursos

  • 🔍 Descoberta de Esquema: Analisa automaticamente as estruturas das coleções
  • ✅ Validação de Campos: Evita erros de nomes de campos
  • 📊 Suporte Completo ao MongoDB: Operações de find, aggregate, insert, update e delete
  • 🚀 Alto Desempenho: Pool de conexões eficiente e otimização de consultas
  • 🔐 Seguro: Suporte ao MongoDB Atlas e autenticação
  • 🎯 Type-Safe: Construído com TypeScript e validação Zod

Instalação

Instalar a partir do npm

npm install -g @sourabhshegane/mongodb-mcp-that-works

Configuração

Este é um servidor MCP stdio padrão. Qualquer cliente MCP o inicia com npx e passa duas variáveis de ambiente:

VariávelObrigatóriaDescrição
MONGODB_URISimString de conexão do MongoDB, ex.: mongodb+srv://user:pass@cluster.mongodb.net/database
MONGODB_DATABASENãoNome padrão do banco de dados (usa o banco da URI como fallback)

Todos os clientes abaixo usam o mesmo comando de inicialização:

npx -y @sourabhshegane/mongodb-mcp-that-works@latest

A flag -y confirma automaticamente a instalação para que o cliente nunca fique travado em um prompt interativo.

Segurança: nunca faça commit de uma string de conexão real. Os exemplos usam placeholders ou referenciam variáveis de ambiente (${env:...}, env_vars, ${input:...}) para que as credenciais fiquem fora do controle de versão.

Claude Desktop

Edite a 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": ["-y", "@sourabhshegane/mongodb-mcp-that-works@latest"],
      "env": {
        "MONGODB_URI": "mongodb+srv://<user>:<password>@cluster.mongodb.net/<database>",
        "MONGODB_DATABASE": "your_database_name"
      }
    }
  }
}

Claude Code

Adicione-o com a CLI (qualquer coisa após -- é o comando do servidor):

claude mcp add mongodb --scope user \
  --env MONGODB_URI=mongodb+srv://<user>:<password>@cluster.mongodb.net/<database> \
  -- npx -y @sourabhshegane/mongodb-mcp-that-works@latest

Ou faça commit de um .mcp.json no escopo do projeto (segredos referenciados com ${VAR}):

{
  "mcpServers": {
    "mongodb": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "@sourabhshegane/mongodb-mcp-that-works@latest"],
      "env": {
        "MONGODB_URI": "${MONGODB_URI}",
        "MONGODB_DATABASE": "${MONGODB_DATABASE:-your_database_name}"
      }
    }
  }
}

Escopos: local → ~/.claude.json, project → .mcp.json, user → ~/.claude.json. Verifique com claude mcp list.

OpenAI Codex

O Codex usa TOML (não JSON). Adicione em ~/.codex/config.toml (ou .codex/config.toml no escopo do projeto):

[mcp_servers.mongodb]
command = "npx"
args = ["-y", "@sourabhshegane/mongodb-mcp-that-works@latest"]
env = { MONGODB_URI = "mongodb+srv://<user>:<password>@cluster.mongodb.net/<database>", MONGODB_DATABASE = "your_database_name" }
startup_timeout_sec = 30

Ou encaminhe variáveis do seu shell em vez de inseri-las diretamente:

[mcp_servers.mongodb]
command = "npx"
args = ["-y", "@sourabhshegane/mongodb-mcp-that-works@latest"]
env_vars = ["MONGODB_URI", "MONGODB_DATABASE"]

Ou adicione-o com a CLI: codex mcp add mongodb -- npx -y @sourabhshegane/mongodb-mcp-that-works@latest. Verifique com codex mcp list.

Cursor

Escopo do projeto — .cursor/mcp.json (faça commit para compartilhar com sua equipe). Escopo global — ~/.cursor/mcp.json.

{
  "mcpServers": {
    "mongodb": {
      "command": "npx",
      "args": ["-y", "@sourabhshegane/mongodb-mcp-that-works@latest"],
      "env": {
        "MONGODB_URI": "${env:MONGODB_URI}",
        "MONGODB_DATABASE": "${env:MONGODB_DATABASE}"
      }
    }
  }
}

VS Code / GitHub Copilot

Para instalação rápida, clique nos botões abaixo. Após a instalação, substitua a string de conexão placeholder na sua configuração:

Install with NPX in VS Code Install with NPX in VS Code Insiders

Observação: a chave raiz do VS Code é servers (outros clientes usam mcpServers), e type é obrigatório. .vscode/mcp.json:

{
  "servers": {
    "mongodb": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "@sourabhshegane/mongodb-mcp-that-works@latest"],
      "env": {
        "MONGODB_URI": "${input:mongodb-uri}"
      }
    }
  },
  "inputs": [
    {
      "id": "mongodb-uri",
      "type": "promptString",
      "description": "MongoDB connection string",
      "password": true
    }
  ]
}

Zed

Adicione em settings.json (~/.config/zed/settings.json ou .zed/settings.json):

{
  "mcp": {
    "mongodb": {
      "command": "npx",
      "args": ["-y", "@sourabhshegane/mongodb-mcp-that-works@latest"],
      "env": {
        "MONGODB_URI": "mongodb+srv://<user>:<password>@cluster.mongodb.net/<database>"
      }
    }
  }
}

Ferramentas Disponíveis

1. listCollections

Lista todas as coleções no banco de dados.

// Example
mcp.listCollections({ filter: {} })

2. find

Encontra documentos em uma coleção com filtragem, ordenação e paginação.

// Example
mcp.find({
  collection: "users",
  filter: { status: "active" },
  sort: { createdAt: -1 },
  limit: 10
})

3. findOne

Encontra um único documento.

// Example
mcp.findOne({
  collection: "users",
  filter: { email: "user@example.com" }
})

4. aggregate

Executa pipelines de agregação.

// Example
mcp.aggregate({
  collection: "orders",
  pipeline: [
    { $match: { status: "completed" } },
    { $group: { _id: "$userId", total: { $sum: "$amount" } } }
  ]
})

5. count

Conta documentos que correspondem a um filtro.

// Example
mcp.count({
  collection: "products",
  filter: { inStock: true }
})

6. distinct

Obtém valores distintos para um campo.

// Example
mcp.distinct({
  collection: "orders",
  field: "status"
})

7. insertOne

Insere um único documento.

// Example
mcp.insertOne({
  collection: "users",
  document: { name: "John Doe", email: "john@example.com" }
})

8. updateOne

Atualiza um único documento.

// Example
mcp.updateOne({
  collection: "users",
  filter: { _id: "123" },
  update: { $set: { status: "active" } }
})

9. deleteOne

Exclui um único documento.

// Example
mcp.deleteOne({
  collection: "users",
  filter: { _id: "123" }
})

10. getSchema

Analisa a estrutura da coleção e descobre nomes de campos.

// Example
mcp.getSchema({
  collection: "users",
  sampleSize: 100
})

// Returns:
{
  "collection": "users",
  "sampleSize": 100,
  "fields": {
    "_id": {
      "types": ["ObjectId"],
      "examples": ["507f1f77bcf86cd799439011"],
      "frequency": "100/100",
      "percentage": 100
    },
    "email": {
      "types": ["string"],
      "examples": ["user@example.com"],
      "frequency": "100/100",
      "percentage": 100
    }
  }
}

Anotações de ferramentas (dicas MCP)

As ferramentas são anotadas com MCP ToolAnnotations para que os clientes possam distinguir ferramentas somente leitura de ferramentas com capacidade de escrita e sinalizar operações destrutivas:

FerramentareadOnlyHintidempotentHintdestructiveHintObservações
listCollectionstrue––Somente leitura
findtrue––Somente leitura
findOnetrue––Somente leitura
aggregatetrue––Somente leitura (pode executar estágios de escrita)
counttrue––Somente leitura
distincttrue––Somente leitura
getSchematrue––Somente leitura
insertOnefalsefalsefalseAditivo; repetir insere um novo documento
updateOnefalsefalsetrueModifica documentos existentes; $inc/$push não são idempotentes
deleteOnefalsetruetrueExcluir um documento já ausente é uma operação sem efeito

Observação: aggregate é anotado como somente leitura, mas pode conter estágios de escrita (ex.: $out, $merge) — inspecione os pipelines antes de executar.

Melhores Práticas

  1. Use a Descoberta de Esquema Primeiro: Antes de consultar, execute getSchema para entender os nomes dos campos
  2. Lide com ObjectIds: O servidor converte automaticamente IDs de string em ObjectIds
  3. Use Projeções: Limite os campos retornados para melhorar o desempenho
  4. Operações em Lote: Use pipelines de agregação para consultas complexas

Exemplos

Uso Básico

// Get schema first to avoid field name mistakes
const schema = await mcp.getSchema({ collection: "reports" });

// Use correct field names from schema
const reports = await mcp.find({
  collection: "reports",
  filter: { organization_id: "64ba7374f8b63db2083b2665" },
  limit: 10
});

Agregação Avançada

const analytics = await mcp.aggregate({
  collection: "orders",
  pipeline: [
    { $match: { createdAt: { $gte: new Date("2024-01-01") } } },
    { $group: {
      _id: { $dateToString: { format: "%Y-%m", date: "$createdAt" } },
      revenue: { $sum: "$amount" },
      count: { $sum: 1 }
    }},
    { $sort: { _id: 1 } }
  ]
});

Depuração

Você pode usar o MCP Inspector para depurar o servidor, inspecionar esquemas de ferramentas e chamar ferramentas interativamente:

npx @modelcontextprotocol/inspector npx -y @sourabhshegane/mongodb-mcp-that-works@latest

Defina MONGODB_URI (e opcionalmente MONGODB_DATABASE) no seu ambiente antes de iniciar o inspector.

Solução de Problemas

Problemas de Conexão

  • Verifique se a URI do MongoDB está correta
  • Verifique a conectividade de rede com o MongoDB Atlas
  • Garanta que a lista de permissões de IP inclua seu IP atual

Erros de Nomes de Campos

  • Sempre use getSchema para descobrir os nomes corretos dos campos
  • Lembre-se de que o MongoDB diferencia maiúsculas de minúsculas
  • Verifique erros de digitação em caminhos de campos aninhados (ex.: "user.profile.name")

Desempenho

  • Use índices para campos consultados com frequência
  • Limite os conjuntos de resultados com o parâmetro limit
  • Use projeções para retornar apenas os campos necessários

Testes

O repositório inclui uma suíte de testes automatizada (node:test, sem framework extra):

npm test

Isso primeiro compila e depois executa:

  • Testes unitários (tests/unit.test.mjs) — protocolo MCP: versão negociada, os 10 esquemas de ferramentas, ToolAnnotations e tratamento de erros. Nenhum banco de dados necessário.
  • Testes de ponta a ponta (tests/e2e.test.mjs) — tour completo de CRUD contra um MongoDB real (insertOne → find/findOne/count/distinct/aggregate → updateOne → getSchema → deleteOne), além de conversão automática de ObjectId e verificações de idempotência. Pula automaticamente com uma nota quando nenhum MongoDB está acessível.

A suíte se conecta ao MongoDB em MONGODB_URI (padrão mongodb://127.0.0.1:27017) e usa um banco de dados descartável que é excluído depois, então é segura contra quaisquer dados existentes. A CI executa ambas as suítes contra um MongoDB real (Docker mongo:7) em cada push/PR.

Contribuindo

Contribuições são bem-vindas — novas ferramentas, correções de bugs, exemplos e melhorias na documentação. Pull requests e issues são apreciados. Veja CHANGELOG.md para o histórico de versões. Para exemplos de outros servidores MCP, veja as implementações de referência.

Licença

Licença MIT — veja o arquivo LICENSE para detalhes

Changelog

Veja CHANGELOG.md para o histórico completo.

VersãonpmGitHub ReleaseDestaques
0.1.8npmv0.1.8Suíte de testes automatizada unitária + e2e MongoDB
0.1.7npmv0.1.7ToolAnnotations, SDK 1.30, documentação padrão do repositório
0.1.6npmv0.1.6CI/CD, changelog e badges do repositório
0.1.5npmv0.1.5Correções de metadados e propriedade pós-migração
0.1.3npmv0.1.3Publicado com documentação de instalação @latest
0.1.2npmv0.1.2URLs do repositório atualizadas para mongodb-mcp-that-works
0.1.0npmv0.1.0Lançamento inicial

Releases

Todas as versões publicadas no npm também têm GitHub Releases marcadas com verificações de build. O repositório usa GitHub Actions para integração contínua e publicação automatizada:

  • Pushes de tags (v*) disparam verificações de lint/build e, quando as verificações passam, uma publicação automatizada no npm
  • Cada versão publicada tem um GitHub Release correspondente

Feito por necessidade, já que o MongoDB MCP oficial não funcionou para mim