MongoDB MCP Server

Un servidor para realizar operaciones CRUD en una base de datos MongoDB.

GitHubPrueba este MCPPatrocinado

Documentación

MongoDB MCP Server

Servidor MongoDB MCP (Model Context Protocol) basado en FastMCP y la herramienta uv, que proporciona funcionalidad completa de operaciones CRUD.

Características

  • ✅ Gestión de conexiones: Conectar y desconectar bases de datos MongoDB
  • ✅ Crear documentos: Insertar nuevos documentos en colecciones
  • ✅ Leer documentos: Consultar documentos de colecciones, con soporte de filtros y paginación
  • ✅ Actualizar documentos: Actualizar documentos en colecciones, con soporte de upsert
  • ✅ Eliminar documentos: Eliminar documentos de colecciones
  • ✅ Manejo de errores: Manejo completo de errores y registro de actividades
  • ✅ Serialización de datos: Manejo automático de tipos especiales de MongoDB como ObjectId

Instalación de dependencias

Instale las dependencias del proyecto con uv:

# 安装 uv（如果还没安装）
curl -LsSf https://astral.sh/uv/install.sh | sh

# 安装项目依赖
uv pip install -e .

O con pip:

pip install -e .

Descripción de herramientas

1. connect - Conectar a la base de datos

Conecta a una base de datos MongoDB.

Parámetros:

  • connection_string (str): Cadena de conexión de MongoDB
  • database_name (str): Nombre de la base de datos

Ejemplo:

{
  "connection_string": "mongodb://localhost:27017",
  "database_name": "myapp"
}

2. disconnect - Desconectar

Desconecta la conexión actual de MongoDB.

Parámetros: Ninguno

3. create - Crear documento

Crea un nuevo documento en la colección especificada.

Parámetros:

  • collection_name (str): Nombre de la colección
  • document (dict): Contenido del documento a insertar

Ejemplo:

{
  "collection_name": "users",
  "document": {
    "name": "张三",
    "age": 25,
    "email": "zhangsan@example.com"
  }
}

4. read - Leer documentos

Lee documentos de la colección especificada.

Parámetros:

  • collection_name (str): Nombre de la colección
  • filter (dict, opcional): Condiciones de filtro de consulta
  • limit (int, opcional): Límite de cantidad de resultados
  • skip (int, opcional): Número de documentos a omitir

Ejemplo:

{
  "collection_name": "users",
  "filter": {"age": {"$gte": 18}},
  "limit": 10,
  "skip": 0
}

5. update - Actualizar documento

Actualiza documentos en la colección especificada.

Parámetros:

  • collection_name (str): Nombre de la colección
  • filter (dict): Condiciones de actualización
  • update (dict): Operación de actualización
  • upsert (bool, opcional): Si se debe crear si el documento no existe, el valor predeterminado es false

Ejemplo:

{
  "collection_name": "users",
  "filter": {"name": "张三"},
  "update": {"$set": {"age": 26}},
  "upsert": false
}

6. delete - Eliminar documento

Elimina documentos de la colección especificada.

Parámetros:

  • collection_name (str): Nombre de la colección
  • filter (dict): Condiciones de eliminación

Ejemplo:

{
  "collection_name": "users",
  "filter": {"age": {"$lt": 18}}
}

Métodos de uso

Ejecutar como servidor MCP

# 直接运行
python -m my_mongo_mcp.server

# 或者使用安装的脚本
my-mongo-mcp

Uso en Claude Desktop

Agregue lo siguiente al archivo de configuración de Claude Desktop:

{
  "mcpServers": {
    "mongodb": {
      "command": "python",
      "args": ["-m", "my_mongo_mcp.server"],
      "env": {}
    }
  }
}

Uso mediante programación

Consulte el archivo example_usage.py:

python example_usage.py

Ejemplos de uso

Operaciones CRUD básicas

  1. Conectar a la base de datos

    工具: connect
参数: {"connection_string": "mongodb://localhost:27017", "database_name": "testdb"}

  2. Crear documento de usuario

    工具: create
参数: {
  "collection_name": "users",
  "document": {"name": "李四", "age": 30, "city": "上海"}
}

  3. Consultar usuarios

    工具: read
参数: {
  "collection_name": "users",
  "filter": {"city": "上海"},
  "limit": 5
}

  4. Actualizar información de usuario

    工具: update
参数: {
  "collection_name": "users",
  "filter": {"name": "李四"},
  "update": {"$set": {"age": 31}}
}

  5. Eliminar usuario

    工具: delete
参数: {
  "collection_name": "users",
  "filter": {"name": "李四"}
}

  6. Desconectar

    工具: disconnect

Notas importantes

  • Asegúrese de que el servidor MongoDB esté en ejecución antes de usar
  • Todas las operaciones requieren una conexión previa a la base de datos
  • Los tipos especiales como ObjectId se convierten automáticamente a cadenas
  • Se admite toda la sintaxis estándar de consulta de MongoDB
  • Los mensajes de error se devuelven en chino

Requisitos del sistema

  • Python 3.8+
  • MongoDB 3.6+
  • fastmcp 0.2.0+
  • pymongo 4.6.0+

Solución de problemas

  1. Error de conexión

    • Verifique que el servicio de MongoDB esté iniciado
    • Valide que la cadena de conexión sea correcta
    • Compruebe la conexión de red y la configuración del firewall

  2. Errores de permisos

    • Asegúrese de que el usuario de MongoDB tenga permisos suficientes
    • Verifique los permisos de acceso a la base de datos y las colecciones

  3. Errores de tipo de datos

    • Asegúrese de que el formato de datos JSON sea correcto
    • Preste atención a los requisitos de formato de ObjectId "# mongodb-mcp-server"