Servidor MongoDB MCP
Un servidor de Protocolo de Contexto de Modelo que permite a los LLM interactuar con bases de datos MongoDB. Este servidor proporciona capacidades para inspeccionar esquemas de colección y ejecutar operaciones MongoDB a través de una interfaz estandarizada.
Manifestación
Características principales
Manejo inteligente de ObjectId
- Conversión inteligente entre identificadores de cadena y ObjectId de MongoDB
- Configurable con el parámetro
objectIdMode :"auto" : Convertir según los nombres de campo (predeterminado)"none" : Sin conversión"force" : fuerza todos los campos de ID de cadena a ObjectId
Configuración flexible
- Variables de entorno :
MCP_MONGODB_URI : URI de conexión de MongoDBMCP_MONGODB_READONLY : Habilita el modo de solo lectura cuando se establece en "verdadero"
- Opciones de línea de comandos :
--read-only o -r : Conectarse en modo de solo lectura
Modo de solo lectura
- Protección contra operaciones de escritura (actualizar, insertar, crear índice)
- Utiliza la preferencia de lectura secundaria de MongoDB para un rendimiento óptimo
- Ideal para conectarse de forma segura a bases de datos de producción
Operaciones de MongoDB
- Operaciones de lectura :
- Consultar documentos con análisis de plan de ejecución opcional
- Ejecutar canalizaciones de agregación
- Contar documentos que coinciden con los criterios
- Obtener información del esquema de colección
- Operaciones de escritura (cuando no está en modo de solo lectura):
- Actualizar documentos
- Insertar nuevos documentos
- Crear índices
Integración de LLM
- Finalización de colecciones para una mejor interacción LLM
- Inferencia de esquemas para una mejor comprensión del contexto
- Análisis de recopilación de datos para obtener información
Instalación
Instalación global
npm install -g mcp-mongo-server
Para el desarrollo
# Clone repository
git clone https://github.com/kiliczsh/mcp-mongo-server.git
cd mcp-mongo-server
# Install dependencies
npm install
# Build
npm run build
# Development with auto-rebuild
npm run watch
Uso
Uso básico
# Start server with MongoDB URI
npx -y mcp-mongo-server mongodb://muhammed:kilic@localhost:27017/database
# Connect in read-only mode
npx -y mcp-mongo-server mongodb://muhammed:kilic@localhost:27017/database --read-only
Variables de entorno
Puede configurar el servidor usando variables de entorno, lo que es particularmente útil para pipelines de CI/CD, contenedores Docker o cuando no desea exponer detalles de conexión en los argumentos del comando:
# Set MongoDB connection URI
export MCP_MONGODB_URI="mongodb://muhammed:kilic@localhost:27017/database"
# Enable read-only mode
export MCP_MONGODB_READONLY="true"
# Run server (will use environment variables if no URI is provided)
npx -y mcp-mongo-server
Uso de variables de entorno en la configuración de Claude Desktop:
{
"mcpServers": {
"mongodb-env": {
"command": "npx",
"args": [
"-y",
"mcp-mongo-server"
],
"env": {
"MCP_MONGODB_URI": "mongodb://muhammed:kilic@localhost:27017/database",
"MCP_MONGODB_READONLY": "true"
}
}
}
}
Uso de variables de entorno con Docker:
# Build
docker build -t mcp-mongo-server .
# Run
docker run -it -d -e MCP_MONGODB_URI="mongodb://muhammed:kilic@localhost:27017/database" -e MCP_MONGODB_READONLY="true" mcp-mongo-server
# or edit docker-compose.yml and run
docker-compose up -d
Integración con Claude Desktop
Configuración manual
Agregue la configuración del servidor al archivo de configuración de Claude Desktop:
MacOS : ~/Library/Application Support/Claude/claude_desktop_config.json Windows : %APPDATA%/Claude/claude_desktop_config.json
Enfoque de argumentos de línea de comandos:
{
"mcpServers": {
"mongodb": {
"command": "npx",
"args": [
"-y",
"mcp-mongo-server",
"mongodb://muhammed:kilic@localhost:27017/database"
]
},
"mongodb-readonly": {
"command": "npx",
"args": [
"-y",
"mcp-mongo-server",
"mongodb://muhammed:kilic@localhost:27017/database",
"--read-only"
]
}
}
}
Enfoque de variables ambientales:
{
"mcpServers": {
"mongodb": {
"command": "npx",
"args": [
"-y",
"mcp-mongo-server"
],
"env": {
"MCP_MONGODB_URI": "mongodb://muhammed:kilic@localhost:27017/database"
}
},
"mongodb-readonly": {
"command": "npx",
"args": [
"-y",
"mcp-mongo-server"
],
"env": {
"MCP_MONGODB_URI": "mongodb://muhammed:kilic@localhost:27017/database",
"MCP_MONGODB_READONLY": "true"
}
}
}
}
Uso del paquete de GitHub:
{
"mcpServers": {
"mongodb": {
"command": "npx",
"args": [
"-y",
"github:kiliczsh/mcp-mongo-server",
"mongodb://muhammed:kilic@localhost:27017/database"
]
},
"mongodb-readonly": {
"command": "npx",
"args": [
"-y",
"github:kiliczsh/mcp-mongo-server",
"mongodb://muhammed:kilic@localhost:27017/database",
"--read-only"
]
}
}
}
Integración con Windsurf y Cursor
El servidor MongoDB MCP se puede utilizar con Windsurf y Cursor de forma similar a Claude Desktop.
Configuración de windsurf
Añade el servidor a tu configuración de Windsurf:
{
"mcpServers": {
"mongodb": {
"command": "npx",
"args": [
"-y",
"mcp-mongo-server",
"mongodb://muhammed:kilic@localhost:27017/database"
]
}
}
}
Configuración del cursor
Para Cursor, agregue la configuración del servidor a sus configuraciones:
{
"mcpServers": {
"mongodb": {
"command": "npx",
"args": [
"-y",
"mcp-mongo-server",
"mongodb://muhammed:kilic@localhost:27017/database"
]
}
}
}
También puede utilizar el enfoque de variables de entorno con Windsurf y Cursor, siguiendo el mismo patrón que se muestra en la configuración de Claude Desktop.
Instalación automatizada
Uso de herrería :
npx -y @smithery/cli install mcp-mongo-server --client claude
Usando mcp-get :
npx @michaellatman/mcp-get@latest install mcp-mongo-server
Herramientas disponibles
Operaciones de consulta
- consulta : Ejecutar consultas MongoDB
{
collection: "users",
filter: { age: { $gt: 30 } },
projection: { name: 1, email: 1 },
limit: 20,
explain: "executionStats" // Optional
}
- agregado : ejecutar canalizaciones de agregación
{
collection: "orders",
pipeline: [
{ $match: { status: "completed" } },
{ $group: { _id: "$customerId", total: { $sum: "$amount" } } }
],
explain: "queryPlanner" // Optional
}
- count : contar documentos coincidentes
{
collection: "products",
query: { category: "electronics" }
}
Operaciones de escritura
- actualización : Modificar documentos
{
collection: "posts",
filter: { _id: "60d21b4667d0d8992e610c85" },
update: { $set: { title: "Updated Title" } },
upsert: false,
multi: false
}
- Insertar : Agregar nuevos documentos
{
collection: "comments",
documents: [
{ author: "user123", text: "Great post!" },
{ author: "user456", text: "Thanks for sharing" }
]
}
- createIndex : Crea índices de colección
{
collection: "users",
indexes: [
{
key: { email: 1 },
unique: true,
name: "email_unique_idx"
}
]
}
Operaciones del sistema
- serverInfo : Obtener detalles del servidor MongoDB
{
includeDebugInfo: true // Optional
}
Depuración
Dado que los servidores MCP se comunican a través de stdio, la depuración puede ser complicada. Utilice el Inspector MCP para una mejor visibilidad:
Esto proporcionará una URL para acceder a las herramientas de depuración en su navegador.
Licencia
Este servidor MCP cuenta con la licencia MIT. Esto significa que puede usar, modificar y distribuir el software libremente, sujeto a los términos y condiciones de la licencia MIT. Para más detalles, consulte el archivo de LICENCIA en el repositorio del proyecto.