MongoDB MCP Server

Un servidor del Model Context Protocol para interactuar con bases de datos MongoDB y MongoDB Atlas.

📚 Tabla de contenido

• 🚀 Primeros pasos

  • Requisitos previos

  • Configuración

    • Inicio rápido

• 🛠️ Herramientas compatibles

  • Herramientas de MongoDB Atlas

  • Herramientas de base de datos MongoDB

• ⚙️ Configuración

  • Opciones de configuración

  • Acceso a la API de Atlas

  • Métodos de configuración

    • Variables de entorno

    • Argumentos de línea de comandos

    • Configuración del cliente MCP

• 🤝 Contribuciones

Requisitos previos

• Node.js (v20.10.0 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.

  • Se requieren credenciales de cuentas de servicio de la API de Atlas 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

Nota: Al usar credenciales de la API de Atlas, asegúrese de asignar solo los permisos mínimos necesarios a su cuenta de servicio. Consulte Permisos de la API de Atlas para más detalles.

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 según el cliente. 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

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 una contraseña válidos.

{
  "mcpServers": {
    "MongoDB": {
      "command": "npx",
      "args": [
        "-y",
        "mongodb-mcp-server",
        "--connectionString",
        "mongodb://localhost:27017/myDatabase"
      ]
    }
  }
}

NOTA: La cadena de conexión se puede configurar para conectarse a cualquier clúster de MongoDB, ya sea una instancia local o un clúster de Atlas.

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

Use las credenciales de cuentas 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 mediante 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 sus cuentas de servicio de Atlas, consulte Acceso a la API de Atlas

Opción 4: Servicio independiente mediante variables de entorno

 npx -y mongodb-mcp-server

Puede usar variables de entorno en el archivo de configuración o definirlas 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

Opción 5: Uso de Docker

Puede ejecutar el MongoDB MCP Server en un contenedor Docker, lo que proporciona aislamiento y no requiere una instalación local de Node.js.

Ejecutar con variables de entorno

Puede proporcionar una cadena de conexión de MongoDB O credenciales de la API de Atlas:

Opción A: Sin configuración

docker run --rm -i \
  mongodb/mongodb-mcp-server:latest

Opción B: Con cadena de conexión de MongoDB

docker run --rm -i \
  -e MDB_MCP_CONNECTION_STRING="mongodb+srv://username:password@cluster.mongodb.net/myDatabase" \
  mongodb/mongodb-mcp-server:latest

Opción C: Con credenciales de la API de Atlas

docker run --rm -i \
  -e MDB_MCP_API_CLIENT_ID="your-atlas-service-accounts-client-id" \
  -e MDB_MCP_API_CLIENT_SECRET="your-atlas-service-accounts-client-secret" \
  mongodb/mongodb-mcp-server:latest

Docker en el archivo de configuración MCP

Sin opciones:

{
  "mcpServers": {
    "MongoDB": {
      "command": "docker",
      "args": ["run", "--rm", "-i", "mongodb/mongodb-mcp-server:latest"]
    }
  }
}

Con cadena de conexión:

{
  "mcpServers": {
    "MongoDB": {
      "command": "docker",
      "args": [
        "run",
        "--rm",
        "-i",
        "-e",
        "MDB_MCP_CONNECTION_STRING=mongodb+srv://username:password@cluster.mongodb.net/myDatabase",
        "mongodb/mongodb-mcp-server:latest"
      ]
    }
  }
}

Con credenciales de la API de Atlas:

{
  "mcpServers": {
    "MongoDB": {
      "command": "docker",
      "args": [
        "run",
        "--rm",
        "-i",
        "-e",
        "MDB_MCP_API_CLIENT_ID=your-atlas-service-accounts-client-id",
        "-e",
        "MDB_MCP_API_CLIENT_SECRET=your-atlas-service-accounts-client-secret",
        "mongodb/mongodb-mcp-server:latest"
      ]
    }
  }
}

🛠️ Herramientas compatibles

Lista de herramientas

Herramientas de MongoDB Atlas

• atlas-list-orgs - Listar las organizaciones de MongoDB Atlas

• atlas-list-projects - Listar los proyectos de MongoDB Atlas

• atlas-create-project - Crear un nuevo proyecto de MongoDB Atlas

• atlas-list-clusters - Listar los clústeres de MongoDB Atlas

• atlas-inspect-cluster - Inspeccionar un clúster específico de MongoDB Atlas

• atlas-create-free-cluster - Crear un clúster gratuito de MongoDB Atlas

• atlas-connect-cluster - Conectarse al clúster de MongoDB Atlas

• atlas-inspect-access-list - Inspeccionar los rangos IP/CIDR con acceso a los clústeres de MongoDB Atlas

• atlas-create-access-list - Configurar la lista de acceso IP/CIDR para los clústeres de MongoDB Atlas

• atlas-list-db-users - Listar los usuarios de bases de datos de MongoDB Atlas

• atlas-create-db-user - Crear un usuario de base de datos de MongoDB Atlas

• atlas-list-alerts - Listar las alertas de MongoDB Atlas para un proyecto

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

Herramientas de base de datos MongoDB

• connect - Conectarse a una instancia de MongoDB

• find - Ejecutar una consulta find contra una colección de MongoDB

• aggregate - Ejecutar una agregación contra una colección de MongoDB

• count - Obtener el número de documentos en una colección de MongoDB

• insert-one - Insertar un solo documento en una colección de MongoDB

• insert-many - Insertar varios documentos en una colección de MongoDB

• create-index - Crear un índice para una colección de MongoDB

• update-one - Actualizar un solo documento en una colección de MongoDB

• update-many - Actualizar varios documentos en una colección de MongoDB

• rename-collection - Renombrar una colección de MongoDB

• delete-one - Eliminar un solo documento de una colección de MongoDB

• delete-many - Eliminar varios documentos de una colección de MongoDB

• drop-collection - Eliminar una colección de una base de datos de MongoDB

• drop-database - Eliminar una base de datos de MongoDB

• list-databases - Listar todas las bases de datos para una conexión de MongoDB

• list-collections - Listar todas las colecciones para una base de datos determinada

• collection-indexes - Describir los índices de una colección

• collection-schema - Describir el esquema de una colección

• collection-storage-size - Obtener el tamaño de una colección en MB

• db-stats - Devolver estadísticas sobre una base de datos de MongoDB

Configuración

El MongoDB MCP Server se puede configurar mediante varios métodos, con la siguiente precedencia (de mayor a menor):

1. Argumentos de línea de comandos

2. Variables de entorno

Opciones de configuración

Ruta de registro

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 mediante la opción disabledTools. Esta opción acepta una matriz de cadenas, donde cada cadena puede ser un nombre de herramienta, un tipo de operación o una categoría.

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

• Para la configuración mediante variables de entorno, use una cadena separada por comas: export MDB_MCP_DISABLED_TOOLS="create,update,delete,atlas,collectionSchema".

• Para la configuración mediante argumentos 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 de MongoDB, como find, aggregate, etc.

Tipos de operación:

• create - Herramientas que crean recursos, como crear clúster, insertar documento, etc.

• update - Herramientas que actualizan recursos, como actualizar documento, renombrar colección, etc.

• delete - Herramientas que eliminan recursos, como eliminar documento, eliminar colección, 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 colección, etc.

Modo de solo lectura

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

Esto es útil para escenarios en los que 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 mediante:

• 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 registraron debido a esta restricción.

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 mediante:

• 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 utilizar las herramientas de la API de Atlas, deberá crear una cuenta de servicio en MongoDB Atlas:

ℹ️ Nota: Para obtener un desglose detallado de los permisos mínimos requeridos para cada operación de Atlas, consulte la sección Permisos de la API de Atlas a continuación.

1. 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 el nombre, la descripción y la expiración de su cuenta de servicio (por ejemplo, "MCP, MCP Server Access, 7 days")

   • Asigne solo los permisos mínimos necesarios para su caso de uso.

     • Consulte Permisos de la API de Atlas para obtener más detalles.

   • Haga clic en "Create"

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

2. Guardar las credenciales del cliente:

   • Después de la creación, se le mostrarán el Client ID y el Client Secret

   • Importante: Copie y guarde el Client Secret inmediatamente, ya que no se mostrará nuevamente

3. Agregar entrada a la lista de acceso:

   • Agregue su dirección IP a la lista de acceso de la API

4. Configurar el servidor MCP:

   • Use uno de los métodos de configuración a continuación para establecer su apiClientId y apiClientSecret

Permisos de la API de Atlas

Advertencia de seguridad: Otorgar el rol de Organization Owner rara vez es necesario y puede ser un riesgo de seguridad. Asigne solo los permisos mínimos necesarios para su caso de uso.

Referencia rápida: Roles requeridos por operación

• Prefiera roles a nivel de proyecto para la mayoría de las operaciones. Asigne solo a los proyectos específicos que necesite gestionar o ver.

• Evite Organization Owner a menos que requiera control administrativo completo sobre todos los proyectos y configuraciones de la organización.

Para obtener una lista completa de roles y sus privilegios, consulte la documentación de roles de usuario de Atlas.

Métodos de configuración

Variables de entorno

Establezca variables de entorno con el prefijo MDB_MCP_ seguido del nombre de la opción en mayúsculas y 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"

export MDB_MCP_LOG_PATH="/path/to/logs"

Ejemplos de archivos de configuración de 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" --logPath=/path/to/logs

Ejemplos de archivos de configuración de 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! Consulte nuestra Guía de contribuciones para conocer las pautas sobre contribuciones de código, estándares, adición de nuevas herramientas e información de solución de problemas.