Mongo-MCP

Um servidor MCP para interagir com um banco de dados MongoDB.

GitHub
3
Experimente este MCPPatrocinado

Documentação

Mongo-MCP

smithery badge English | 简体中文

Um serviço Machine Chat Protocol (MCP) para operações com MongoDB. Este serviço fornece um conjunto abrangente de ferramentas que permitem que Modelos de Linguagem de Grande Porte (LLMs) interajam com bancos de dados MongoDB por meio de operações CRUD completas, tarefas administrativas e recursos avançados.

Requisitos

  • Python 3.10 ou superior
  • Um serviço de banco de dados MongoDB em execução
  • Recomenda-se usar uv para executar o programa

🚀 Recursos

📊 Ferramentas de Gerenciamento de Banco de Dados

  • list_databases - Listar todos os bancos de dados
  • create_database - Criar novo banco de dados
  • drop_database - Excluir banco de dados
  • get_database_stats - Obter estatísticas do banco de dados

📦 Ferramentas de Gerenciamento de Coleções

  • list_collections - Listar todas as coleções em um banco de dados
  • create_collection - Criar nova coleção (com configurações opcionais)
  • drop_collection - Excluir coleção
  • rename_collection - Renomear coleção
  • get_collection_stats - Obter estatísticas da coleção

📄 Operações CRUD de Documentos

  • insert_document - Inserir documento único
  • insert_many_documents - Inserir múltiplos documentos em lote
  • find_documents - Consultar documentos (suporta ordenação, projeção, limite)
  • find_one_document - Consultar documento único
  • count_documents - Contar documentos que correspondem à consulta
  • update_document - Atualizar documentos (único ou em lote)
  • replace_document - Substituir documento
  • delete_document - Excluir documentos (único ou em lote)

🔍 Ferramentas de Gerenciamento de Índices

  • list_indexes - Listar todos os índices de uma coleção
  • create_index - Criar índice regular
  • create_text_index - Criar índice de busca de texto
  • create_compound_index - Criar índice composto
  • drop_index - Excluir índice
  • reindex_collection - Reconstruir todos os índices de uma coleção

📈 Operações de Agregação

  • aggregate_documents - Executar operações de pipeline de agregação
  • distinct_values - Obter valores distintos para um campo

🔧 Ferramentas de Monitoramento e Administração

  • get_server_status - Obter status do servidor MongoDB
  • get_replica_set_status - Obter status do conjunto de réplicas
  • ping_database - Testar conexão com o banco de dados
  • test_mongodb_connection - Teste de conexão abrangente
  • get_connection_details - Obter informações detalhadas de conexão

🛠️ Stack de Tecnologia

  • Python: Linguagem de programação principal
  • FastMCP: SDK Python do MCP para geração automática de definições de ferramentas
  • PyMongo: Driver oficial do MongoDB para Python
  • uv: Ferramenta moderna de gerenciamento de pacotes Python

Uso

Executar diretamente com uvx

uvx run mongo-mcp

O servidor usa o método de transporte stdio, tornando-o adequado para integração com clientes MCP que suportam este método de transporte.

Exemplo de Configuração no Cursor

Se você usa Cursor como seu ambiente de desenvolvimento, você pode adicionar a seguinte configuração ao seu arquivo .cursor/mcp.json para depuração local:

{
    "mcpServers": {
        "mongo-mcp": {
            "command": "uvx",
            "args": [
                "mongo-mcp"
            ],
            "env": {
                "MONGODB_URI": "mongodb://localhost:27017",
                "MONGODB_DEFAULT_DB": "your_database_name",
                "LOG_LEVEL": "INFO"
            }
        }
    }
}

Variáveis de Ambiente

Configuração Básica

  • MONGODB_URI: String de conexão MongoDB (padrão: "mongodb://localhost:27017")
  • MONGODB_DEFAULT_DB: Nome padrão do banco de dados (opcional)

Configuração do Pool de Conexões

  • MONGODB_MIN_POOL_SIZE: Tamanho mínimo do pool de conexões (padrão: 0)
  • MONGODB_MAX_POOL_SIZE: Tamanho máximo do pool de conexões (padrão: 100)
  • MONGODB_MAX_IDLE_TIME_MS: Tempo máximo de inatividade em milissegundos (padrão: 30000)

Configuração de Timeout

  • MONGODB_SERVER_SELECTION_TIMEOUT_MS: Timeout de seleção do servidor (padrão: 30000)
  • MONGODB_SOCKET_TIMEOUT_MS: Timeout do socket (padrão: 0 - sem timeout)
  • MONGODB_CONNECT_TIMEOUT_MS: Timeout de conexão (padrão: 20000)

Configuração de Segurança

  • MONGODB_TLS_ENABLED: Habilitar conexão TLS (padrão: false)
  • MONGODB_AUTH_SOURCE: Fonte de autenticação (padrão: admin)
  • MONGODB_AUTH_MECHANISM: Mecanismo de autenticação (SCRAM-SHA-1, SCRAM-SHA-256, etc.)

Configurações de Desempenho

  • MONGODB_READ_PREFERENCE: Preferência de leitura (padrão: primary)
  • MONGODB_WRITE_CONCERN_W: Preocupação de escrita (padrão: 1)
  • MONGODB_READ_CONCERN_LEVEL: Nível de preocupação de leitura (padrão: local)

Configuração de Logging

  • LOG_LEVEL: Nível de logging (padrão: "INFO")
    • Valores disponíveis: DEBUG, INFO, WARNING, ERROR, CRITICAL
  • LOG_MAX_FILE_SIZE: Tamanho máximo do arquivo de log em bytes (padrão: 10MB)
  • LOG_BACKUP_COUNT: Número de arquivos de log de backup (padrão: 5)

Flags de Recursos

  • ENABLE_DANGEROUS_OPERATIONS: Habilitar operações potencialmente perigosas (padrão: false)
  • ENABLE_ADMIN_OPERATIONS: Habilitar operações administrativas (padrão: true)
  • ENABLE_INDEX_OPERATIONS: Habilitar operações de índice (padrão: true)

Guia de Desenvolvimento

  1. Clone o repositório
git clone https://github.com/441126098/mongo-mcp.git
cd mongo-mcp
  1. Instale as dependências de desenvolvimento
# Using uv (recommended)
uv sync

# Or using pip
pip install -e ".[dev]"
  1. Execute os testes
uv run pytest tests/ -v
  1. Estrutura do Código
  • src/mongo_mcp/server.py: Implementação do servidor MCP
  • src/mongo_mcp/db.py: Implementação das operações principais do MongoDB
  • src/mongo_mcp/config.py: Gerenciamento de configuração
  • src/mongo_mcp/tools/: Implementação das ferramentas MCP
    • database_tools.py: Gerenciamento de banco de dados e coleções
    • document_tools.py: Operações CRUD de documentos
    • index_tools.py: Gerenciamento de índices
    • aggregation_tools.py: Operações de agregação
    • admin_tools.py: Ferramentas administrativas e de monitoramento
  • src/mongo_mcp/utils/: Módulos utilitários
  • tests/: Casos de teste

Testes

O projeto inclui cobertura abrangente de testes:

  • Testes unitários para todos os módulos de ferramentas
  • Testes de integração com MongoDB
  • Testes simulados para testes isolados de componentes

Execute a suíte de testes:

# Run all tests
uv run pytest

# Run with verbose output
uv run pytest -v

# Run specific test file
uv run pytest tests/test_tools.py

Logging

Os arquivos de log são armazenados no diretório logs por padrão. O sistema de logging suporta:

  • Níveis de log configuráveis
  • Rotação de arquivos baseada em tamanho
  • Suporte a codificação UTF-8
  • Logging estruturado com nomes de funções e números de linha

Licença

MIT

Contribuição

Contribuições via Issues e Pull Requests são bem-vindas. Antes de enviar um PR, certifique-se de:

  1. Todos os testes passam (uv run pytest)
  2. Casos de teste apropriados são adicionados
  3. A documentação é atualizada
  4. O código segue os padrões de estilo existentes