MongoDB That Works

MongoDB That Works - Servidor MCP

Um servidor MongoDB MCP (Model Context Protocol) confiável que fornece integração perfeita com MongoDB para Claude Desktop, com descoberta de esquema e validação de campos integradas.

Recursos

• 🔍 Descoberta de Esquema: Analise automaticamente as estruturas das coleções
• ✅ Validação de Campos: Evite erros de nomes de campos
• 📊 Suporte Completo ao MongoDB: Operações de find, aggregate, insert, update, delete
• 🚀 Alto Desempenho: Pool de conexões eficiente e otimização de consultas
• 🔐 Seguro: Suporte para 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

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

Opções de Configuração

• MONGODB_URI: Sua string de conexão MongoDB (obrigatório)
• MONGODB_DATABASE: Nome do banco de dados padrão (opcional)

Ferramentas Disponíveis

1. listCollections

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

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

2. find

Encontre 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

Encontre um único documento.

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

4. aggregate

Execute pipelines de agregação.

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

5. count

Conte documentos que correspondem a um filtro.

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

6. distinct

Obtenha valores distintos para um campo.

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

7. insertOne

Insira um único documento.

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

8. updateOne

Atualize um único documento.

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

9. deleteOne

Exclua um único documento.

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

10. getSchema

Analise a estrutura da coleção e descubra 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
    }
  }
}

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 para 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 } }
  ]
});

Solução de Problemas

Problemas de Conexão

• Verifique se sua 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 nomes de campos corretos
• Lembre-se de que o MongoDB diferencia maiúsculas de minúsculas
• Verifique erros de digitação em caminhos de campos aninhados (por exemplo, "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

Licença

Licença MIT - consulte o arquivo LICENSE para obter detalhes

Changelog

v0.1.0

• Lançamento inicial
• Operações CRUD completas do MongoDB
• Ferramenta de descoberta de esquema
• Conversão automática de ObjectId
• Suporte a TypeScript

---

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