MongoDB MCP Server

Un servidor para interactuar con bases de datos MongoDB y MongoDB Atlas.

GitHubPrueba este MCPPatrocinado

Documentación

MongoDB MCP Server

Un servidor de Protocolo de Contexto de Modelo (MCP) para interactuar con bases de datos MongoDB y MongoDB Atlas.

📚 Tabla de Contenidos

🚀 Comenzando
- Requisitos previos
- Configuración
  - Inicio rápido
🛠️ Herramientas compatibles
- Herramientas de MongoDB Atlas
- Herramientas de base de datos MongoDB
⚙️ Configuración
🤝 Contribuciones

Requisitos previos

Node.js (v20 o posterior)

node -v

Una cadena de conexión de MongoDB o credenciales de la API de Atlas, el servidor no se iniciará a menos que esté configurado.
- Las credenciales de la API de Atlas para cuentas de servicio son necesarias para usar las herramientas de Atlas. Puede crear una cuenta de servicio en MongoDB Atlas y usar sus credenciales para la autenticación. Consulte Acceso a la API de Atlas para más detalles.
- Si tiene una cadena de conexión de MongoDB, puede usarla directamente para conectarse a su instancia de MongoDB.

Configuración

Inicio rápido

La mayoría de los clientes MCP requieren que se cree o modifique un archivo de configuración para agregar el servidor MCP.

Nota: La sintaxis del archivo de configuración puede variar entre clientes. Consulte los siguientes enlaces para conocer la sintaxis esperada más reciente:

Windsurf:https://docs.windsurf.com/windsurf/mcp
VSCode: https://code.visualstudio.com/docs/copilot/chat/mcp-servers
Claude Desktop: https://modelcontextprotocol.io/quickstart/user
Cursor: https://docs.cursor.com/context/model-context-protocol

🐳 Despliegue con Docker

Proporcionamos imágenes Docker preconstruidas que se pueden descargar a través de GitHub Actions:

Descargar la imagen:

Visite la página de GitHub Actions
Seleccione el registro de compilación más reciente
En la sección "Artifacts", descargue mongodb-mcp-server-{version}-amd64.tar.gz

Cómo usarlo:

# 解压并加载镜像
gunzip mongodb-mcp-server-{version}-amd64.tar.gz
docker load -i mongodb-mcp-server-{version}-amd64.tar

# 运行容器
docker run -d -p 8000:8000 \
  -e MDB_MCP_CONNECTION_STRING="mongodb+srv://username:password@cluster.mongodb.net/myDatabase" \
  -e MDB_DB="myDatabase" \
  mongodb-mcp-server:latest

# 或使用Atlas API凭据
docker run -d -p 8000:8000 \
  -e MDB_MCP_API_CLIENT_ID="your-client-id" \
  -e MDB_MCP_API_CLIENT_SECRET="your-client-secret" \
  mongodb-mcp-server:latest

Variables de entorno de Docker:

PORT: Puerto del servicio (predeterminado: 8000)
MDB_MCP_CONNECTION_STRING: Cadena de conexión de MongoDB
MDB_DB: Nombre de base de datos predeterminado (predeterminado: ChatBI)
MDB_MCP_API_CLIENT_ID: ID de cliente de la API de Atlas
MDB_MCP_API_CLIENT_SECRET: Clave secreta de cliente de la API de Atlas

Opción 1: Argumentos de cadena de conexión

Puede pasar su cadena de conexión mediante argumentos, asegúrese de usar un nombre de usuario y contraseña válidos.

{
  "mcpServers": {
    "MongoDB": {
      "command": "npx",
      "args": [
        "-y",
        "mongodb-mcp-server",
        "--connectionString",
        "mongodb+srv://username:password@cluster.mongodb.net/myDatabase"
      ]
    }
  }
}

Opción 2: Argumentos de credenciales de la API de Atlas

Use las credenciales de su cuenta de servicio de la API de Atlas. Debe seguir todos los pasos de la sección Acceso a la API de Atlas.

{
  "mcpServers": {
    "MongoDB": {
      "command": "npx",
      "args": [
        "-y",
        "mongodb-mcp-server",
        "--apiClientId",
        "your-atlas-service-accounts-client-id",
        "--apiClientSecret",
        "your-atlas-service-accounts-client-secret"
      ]
    }
  }
}

Opción 3: Servicio independiente usando argumentos de comando

Inicie el servidor usando el comando npx:

 npx -y mongodb-mcp-server --apiClientId="your-atlas-service-accounts-client-id" --apiClientSecret="your-atlas-service-accounts-client-secret"

Para obtener una lista completa de argumentos, consulte Opciones de configuración
Para configurar las credenciales de su cuenta de servicio de Atlas, consulte Acceso a la API de Atlas

Opción 4: Servicio independiente usando variables de entorno

 npx -y mongodb-mcp-server

Puede usar variables de entorno en el archivo de configuración o configurarlas y ejecutar el servidor mediante npx.

Cadena de conexión mediante variables de entorno en el archivo MCP ejemplo
Credenciales de la API de Atlas mediante variables de entorno en el archivo MCP ejemplo

🛠️ Herramientas compatibles

Lista de herramientas

Herramientas de MongoDB Atlas

atlas-list-orgs - Lista las organizaciones de MongoDB Atlas
atlas-list-projects - Lista los proyectos de MongoDB Atlas
atlas-create-project - Crea un nuevo proyecto de MongoDB Atlas
atlas-list-clusters - Lista los clústeres de MongoDB Atlas
atlas-inspect-cluster - Inspecciona un clúster específico de MongoDB Atlas
atlas-create-free-cluster - Crea un clúster gratuito de MongoDB Atlas
atlas-connect-cluster - Se conecta al clúster de MongoDB Atlas
atlas-inspect-access-list - Inspecciona los rangos de IP/CIDR con acceso a los clústeres de MongoDB Atlas
atlas-create-access-list - Configura la lista de acceso de IP/CIDR para los clústeres de MongoDB Atlas
atlas-list-db-users - Lista los usuarios de bases de datos de MongoDB Atlas
atlas-create-db-user - Lista los usuarios de bases de datos de MongoDB Atlas

NOTA: las herramientas de Atlas solo están disponibles cuando se configuran credenciales en la sección de configuración.

Herramientas de base de datos MongoDB

connect - Se conecta a una instancia de MongoDB
find - Ejecuta una consulta find en una colección de MongoDB
aggregate - Ejecuta una agregación en una colección de MongoDB
count - Obtiene el número de documentos en una colección de MongoDB
insert-one - Inserta un solo documento en una colección de MongoDB
insert-many - Inserta múltiples documentos en una colección de MongoDB
create-index - Crea un índice para una colección de MongoDB
update-one - Actualiza un solo documento en una colección de MongoDB
update-many - Actualiza múltiples documentos en una colección de MongoDB
rename-collection - Renombra una colección de MongoDB
delete-one - Elimina un solo documento de una colección de MongoDB
delete-many - Elimina múltiples documentos de una colección de MongoDB
drop-collection - Elimina una colección de una base de datos de MongoDB
drop-database - Elimina una base de datos de MongoDB
list-databases - Lista todas las bases de datos para una conexión de MongoDB
list-collections - Lista todas las colecciones para una base de datos determinada
collection-indexes - Describe los índices de una colección
collection-schema - Describe el esquema de una colección
collection-storage-size - Obtiene el tamaño de una colección en MB
db-stats - Devuelve estadísticas sobre una base de datos de MongoDB

Configuración

El servidor MCP de MongoDB se puede configurar usando múltiples métodos, con la siguiente precedencia (de mayor a menor):

Argumentos de línea de comandos
Variables de entorno

Opciones de configuración

Opción	Descripción
`apiClientId`	ID de cliente de la API de Atlas para autenticación
`apiClientSecret`	Clave secreta de cliente de la API de Atlas para autenticación
`connectionString`	Cadena de conexión de MongoDB para conexiones directas a la base de datos (opcional; los usuarios pueden elegir proporcionarla en cada llamada de herramienta)
`defaultDatabase`	Nombre de base de datos predeterminado para operaciones de MongoDB. Se puede configurar mediante el argumento `--database` o las variables de entorno `MDB_DB`/`MDB_MCP_DEFAULT_DATABASE`. El valor predeterminado es "ChatBI"
`logPath`	Carpeta para almacenar registros
`disabledTools`	Una matriz de nombres de herramientas, tipos de operación y/o categorías de herramientas que se deshabilitarán
`readOnly`	Cuando se establece en true, solo permite tipos de operación de lectura y metadatos, deshabilitando operaciones de creación/actualización/eliminación
`telemetry`	Cuando se establece en disabled, deshabilita la recopilación de telemetría

Ruta de registros

La ubicación predeterminada de los registros es la siguiente:

Windows: %LOCALAPPDATA%\mongodb\mongodb-mcp\.app-logs
macOS/Linux: ~/.mongodb/mongodb-mcp/.app-logs

Herramientas deshabilitadas

Puede deshabilitar herramientas específicas o categorías de herramientas usando la opción disabledTools. Esta opción acepta una matriz de cadenas, donde cada cadena puede ser un nombre de herramienta, tipo de operación o categoría.

La forma en que se construye la matriz depende del tipo de método de configuración que use:

Para la configuración mediante variable de entorno, use una cadena separada por comas: export MDB_MCP_DISABLED_TOOLS="create,update,delete,atlas,collectionSchema".
Para la configuración mediante argumento de línea de comandos, use una cadena separada por espacios: --disabledTools create update delete atlas collectionSchema.

Categorías de herramientas:

atlas - Herramientas de MongoDB Atlas, como listar clústeres, crear clústeres, etc.
mongodb - Herramientas de base de datos MongoDB, como find, aggregate, etc.

Tipos de operación:

create - Herramientas que crean recursos, como crear clústeres, insertar documentos, etc.
update - Herramientas que actualizan recursos, como actualizar documentos, renombrar colecciones, etc.
delete - Herramientas que eliminan recursos, como eliminar documentos, eliminar colecciones, etc.
read - Herramientas que leen recursos, como find, aggregate, listar clústeres, etc.
metadata - Herramientas que leen metadatos, como listar bases de datos, listar colecciones, esquema de colecciones, etc.

Modo de solo lectura

La opción de configuración readOnly le permite restringir el servidor MCP para que solo use herramientas con tipos de operación "read" y "metadata". Cuando está habilitado, todas las herramientas que tienen tipos de operación "create", "update" o "delete" no se registrarán en el servidor.

Esto es útil para escenarios donde desea proporcionar acceso a los datos de MongoDB para análisis sin permitir modificaciones en los datos o la infraestructura.

Puede habilitar el modo de solo lectura usando:

Variable de entorno: export MDB_MCP_READ_ONLY=true
Argumento de línea de comandos: --readOnly

Cuando el modo de solo lectura está activo, verá un mensaje en los registros del servidor que indica qué herramientas no se pudieron registrar debido a esta restricción.

Restricción de base de datos

La opción de configuración defaultDatabase le permite restringir el servidor MCP para que opere solo en una base de datos específica. Cuando está configurada, todas las herramientas de base de datos usarán la base de datos especificada de forma predeterminada, y la herramienta list-databases se deshabilita para evitar el descubrimiento de otras bases de datos.

Esto es útil para escenarios donde desea limitar el acceso a una base de datos específica por razones de seguridad u operativas.

Puede configurar la base de datos predeterminada usando:

Variable de entorno: export MDB_DB=ChatBI o export MDB_MCP_DEFAULT_DATABASE=ChatBI
Argumento de línea de comandos: --database ChatBI
Variable de entorno de Docker: -e MDB_DB=ChatBI

Cuando se configura una base de datos predeterminada:

Todas las operaciones de base de datos usarán esta base de datos a menos que se anule explícitamente en los argumentos de la herramienta
La herramienta list-databases se deshabilita para evitar el descubrimiento de bases de datos
Los usuarios aún pueden especificar un nombre de base de datos diferente en llamadas individuales de herramientas si es necesario

Telemetría

La opción de configuración telemetry le permite deshabilitar la recopilación de telemetría. Cuando está habilitada, el servidor MCP recopilará datos de uso y los enviará a MongoDB.

Puede deshabilitar la telemetría usando:

Variable de entorno: export MDB_MCP_TELEMETRY=disabled
Argumento de línea de comandos: --telemetry disabled
Variable de entorno DO_NOT_TRACK: export DO_NOT_TRACK=1

Acceso a la API de Atlas

Para usar las herramientas de la API de Atlas, deberá crear una cuenta de servicio en MongoDB Atlas:

Crear una cuenta de servicio:
- Inicie sesión en MongoDB Atlas en cloud.mongodb.com
- Navegue a Access Manager > Organization Access
- Haga clic en Add New > Applications > Service Accounts
- Ingrese nombre, descripción y fecha de expiración para su cuenta de servicio (por ejemplo, "MCP, Acceso al servidor MCP, 7 días")
- Seleccione los permisos apropiados (para acceso completo, use Organization Owner)
- Haga clic en "Create"

Para obtener más información sobre las cuentas de servicio, consulte la documentación de MongoDB Atlas.

Guardar las credenciales del cliente:
- Después de la creación, se le mostrarán el ID de cliente y la clave secreta del cliente
- Importante: Copie y guarde la clave secreta del cliente inmediatamente, ya que no se mostrará nuevamente
Agregar entrada a la lista de acceso:
- Agregue su dirección IP a la lista de acceso de la API
Configurar el servidor MCP:
- Use uno de los métodos de configuración a continuación para configurar su apiClientId y apiClientSecret

Métodos de configuración

Variables de entorno

Configure variables de entorno con el prefijo MDB_MCP_ seguido del nombre de la opción en mayúsculas con guiones bajos:

# Set Atlas API credentials (via Service Accounts)
export MDB_MCP_API_CLIENT_ID="your-atlas-service-accounts-client-id"
export MDB_MCP_API_CLIENT_SECRET="your-atlas-service-accounts-client-secret"

# Set a custom MongoDB connection string
export MDB_MCP_CONNECTION_STRING="mongodb+srv://username:password@cluster.mongodb.net/myDatabase"

# Set default database for operations (limits MCP to only use this database)
export MDB_MCP_DEFAULT_DATABASE="ChatBI"
# Or alternatively, use the shorter form:
export MDB_DB="ChatBI"

export MDB_MCP_LOG_PATH="/path/to/logs"

Ejemplos de archivos de configuración MCP

Cadena de conexión con variables de entorno

{
  "mcpServers": {
    "MongoDB": {
      "command": "npx",
      "args": ["-y", "mongodb-mcp-server"],
      "env": {
        "MDB_MCP_CONNECTION_STRING": "mongodb+srv://username:password@cluster.mongodb.net/myDatabase"
      }
    }
  }
}

Credenciales de la API de Atlas con variables de entorno

{
  "mcpServers": {
    "MongoDB": {
      "command": "npx",
      "args": ["-y", "mongodb-mcp-server"],
      "env": {
        "MDB_MCP_API_CLIENT_ID": "your-atlas-service-accounts-client-id",
        "MDB_MCP_API_CLIENT_SECRET": "your-atlas-service-accounts-client-secret"
      }
    }
  }
}

Argumentos de línea de comandos

Pase las opciones de configuración como argumentos de línea de comandos al iniciar el servidor:

npx -y mongodb-mcp-server --apiClientId="your-atlas-service-accounts-client-id" --apiClientSecret="your-atlas-service-accounts-client-secret" --connectionString="mongodb+srv://username:password@cluster.mongodb.net/myDatabase" --database="ChatBI" --logPath=/path/to/logs

Ejemplos de archivos de configuración MCP

Cadena de conexión con argumentos de línea de comandos

{
  "mcpServers": {
    "MongoDB": {
      "command": "npx",
      "args": [
        "-y",
        "mongodb-mcp-server",
        "--connectionString",
        "mongodb+srv://username:password@cluster.mongodb.net/myDatabase"
      ]
    }
  }
}

Credenciales de la API de Atlas con argumentos de línea de comandos

{
  "mcpServers": {
    "MongoDB": {
      "command": "npx",
      "args": [
        "-y",
        "mongodb-mcp-server",
        "--apiClientId",
        "your-atlas-service-accounts-client-id",
        "--apiClientSecret",
        "your-atlas-service-accounts-client-secret"
      ]
    }
  }
}

🤝 Contribuciones

¿Interesado en contribuir? ¡Genial! Por favor, consulta nuestra Guía de Contribución para conocer las pautas sobre contribuciones de código, estándares, adición de nuevas herramientas e información de solución de problemas.