MongoDB That Works

MongoDB That Works - Servidor MCP

Un servidor MCP (Protocolo de Contexto de Modelo) de MongoDB confiable que proporciona una integración perfecta de MongoDB para Claude Desktop con descubrimiento de esquemas y validación de campos integrados.

Características

• 🔍 Descubrimiento de Esquemas: Analiza automáticamente las estructuras de las colecciones
• ✅ Validación de Campos: Previene errores en los nombres de los campos
• 📊 Soporte Completo de MongoDB: Operaciones de búsqueda, agregación, inserción, actualización y eliminación
• 🚀 Alto Rendimiento: Agrupación de conexiones eficiente y optimización de consultas
• 🔐 Seguro: Soporte para MongoDB Atlas y autenticación
• 🎯 Seguro de Tipos: Construido con TypeScript y validación Zod

Instalación

Instalar desde npm

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

Configuración

Agrega a tu archivo de configuración de 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"
      }
    }
  }
}

Opciones de Configuración

• MONGODB_URI: Tu cadena de conexión de MongoDB (obligatorio)
• MONGODB_DATABASE: Nombre de la base de datos por defecto (opcional)

Herramientas Disponibles

1. listCollections

Lista todas las colecciones en la base de datos.

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

2. find

Busca documentos en una colección con filtrado, ordenamiento y paginación.

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

3. findOne

Busca un solo documento.

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

4. aggregate

Ejecuta pipelines de agregación.

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

5. count

Cuenta documentos que coinciden con un filtro.

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

6. distinct

Obtiene valores distintos para un campo.

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

7. insertOne

Inserta un solo documento.

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

8. updateOne

Actualiza un solo documento.

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

9. deleteOne

Elimina un solo documento.

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

10. getSchema

Analiza la estructura de la colección y descubre los nombres de los 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
    }
  }
}

Mejores Prácticas

1. Usa el Descubrimiento de Esquemas Primero: Antes de consultar, ejecuta getSchema para entender los nombres de los campos
2. Maneja ObjectIds: El servidor convierte automáticamente los IDs de cadena a ObjectIds
3. Usa Proyecciones: Limita los campos devueltos para mejorar el rendimiento
4. Operaciones por Lotes: Usa pipelines de agregación para consultas complejas

Ejemplos

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

Agregación Avanzada

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

Solución de Problemas

Problemas de Conexión

• Verifica que tu URI de MongoDB sea correcta
• Comprueba la conectividad de red con MongoDB Atlas
• Asegúrate de que la lista blanca de IP incluya tu IP actual

Errores en Nombres de Campos

• Siempre usa getSchema para descubrir los nombres de campos correctos
• Recuerda que MongoDB distingue entre mayúsculas y minúsculas
• Verifica errores tipográficos en rutas de campos anidados (por ejemplo, "user.profile.name")

Rendimiento

• Usa índices para campos consultados con frecuencia
• Limita los conjuntos de resultados con el parámetro limit
• Usa proyecciones para devolver solo los campos necesarios

Licencia

Licencia MIT - consulta el archivo LICENSE para más detalles

Registro de Cambios

v0.1.0

• Lanzamiento inicial
• Operaciones CRUD completas de MongoDB
• Herramienta de descubrimiento de esquemas
• Conversión automática de ObjectId
• Soporte de TypeScript

---

Hecho por necesidad, ya que el MCP oficial de MongoDB no funcionó para mí