MongoDB MCP Server

Um servidor para realizar operações CRUD em um banco de dados MongoDB.

GitHubExperimente este MCPPatrocinado

Documentação

MongoDB MCP Server

Servidor MongoDB MCP (Model Context Protocol) baseado nas ferramentas FastMCP e uv, fornecendo funcionalidades completas de operações CRUD.

Funcionalidades

  • ✅ Gerenciamento de conexão: Conectar e desconectar do banco de dados MongoDB
  • ✅ Criar documentos: Inserir novos documentos em coleções
  • ✅ Ler documentos: Consultar documentos de coleções, com suporte a filtros e paginação
  • ✅ Atualizar documentos: Atualizar documentos em coleções, com suporte a upsert
  • ✅ Excluir documentos: Excluir documentos de coleções
  • ✅ Tratamento de erros: Tratamento de erros e registro de logs abrangentes
  • ✅ Serialização de dados: Processamento automático de tipos especiais do MongoDB, como ObjectId

Instalação de dependências

Instale as dependências do projeto usando uv:

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

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

Ou usando pip:

pip install -e .

Descrição das ferramentas

1. connect - Conectar ao banco de dados

Conecta ao banco de dados MongoDB.

Parâmetros:

  • connection_string (str): String de conexão do MongoDB
  • database_name (str): Nome do banco de dados

Exemplo:

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

2. disconnect - Desconectar

Desconecta a conexão atual do MongoDB.

Parâmetros: Nenhum

3. create - Criar documento

Cria um novo documento na coleção especificada.

Parâmetros:

  • collection_name (str): Nome da coleção
  • document (dict): Conteúdo do documento a ser inserido

Exemplo:

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

4. read - Ler documentos

Lê documentos da coleção especificada.

Parâmetros:

  • collection_name (str): Nome da coleção
  • filter (dict, opcional): Condições de filtro da consulta
  • limit (int, opcional): Limite de quantidade retornada
  • skip (int, opcional): Número de documentos a pular

Exemplo:

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

5. update - Atualizar documento

Atualiza documentos na coleção especificada.

Parâmetros:

  • collection_name (str): Nome da coleção
  • filter (dict): Condições de atualização
  • update (dict): Operação de atualização
  • upsert (bool, opcional): Se deve criar caso o documento não exista, padrão é false

Exemplo:

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

6. delete - Excluir documento

Exclui documentos da coleção especificada.

Parâmetros:

  • collection_name (str): Nome da coleção
  • filter (dict): Condições de exclusão

Exemplo:

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

Como usar

Executar como servidor MCP

# 直接运行
python -m my_mongo_mcp.server

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

Usar no Claude Desktop

Adicione no arquivo de configuração do Claude Desktop:

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

Uso programático

Consulte o arquivo example_usage.py:

python example_usage.py

Exemplos de uso

Operações CRUD básicas

  1. Conectar ao banco de dados

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

  2. Criar documento de usuário

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

  3. Consultar usuário

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

  4. Atualizar informações do usuário

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

  5. Excluir usuário

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

  6. Desconectar

    工具: disconnect

Observações

  • Certifique-se de que o servidor MongoDB esteja em execução antes de usar
  • Todas as operações exigem conexão prévia ao banco de dados
  • Tipos especiais como ObjectId são convertidos automaticamente para strings
  • Suporta toda a sintaxe padrão de consulta do MongoDB
  • Mensagens de erro são retornadas em chinês

Requisitos do sistema

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

Solução de problemas

  1. Falha na conexão

    • Verifique se o serviço MongoDB está iniciado
    • Valide se a string de conexão está correta
    • Verifique a conexão de rede e as configurações de firewall

  2. Erros de permissão

    • Certifique-se de que o usuário do MongoDB tenha permissões suficientes
    • Verifique as permissões de acesso ao banco de dados e às coleções

  3. Erros de tipo de dados

    • Certifique-se de que o formato dos dados JSON esteja correto
    • Preste atenção aos requisitos de formato do ObjectId "# mongodb-mcp-server"