MongoDB Lens

Servidor MCP completo para banco de dados MongoDB.

GitHub
208
Experimente este MCPPatrocinado

Documentação

MongoDB Lens

License Docker Hub Version NPM Version Buy Me a Coffee

MongoDB Lens é um servidor local de Model Context Protocol (MCP) com acesso completo a bancos de dados MongoDB usando linguagem natural por meio de LLMs para realizar consultas, executar agregações, otimizar desempenho e muito mais.

Conteúdo

Início Rápido

Recursos

Ferramentas

Recursos

Prompts

  • aggregation-builder: Criação passo a passo de pipelines de agregação
  • backup-strategy: Recomendações personalizadas de backup e recuperação
  • data-modeling: Consultoria especializada em design de esquemas MongoDB para casos de uso específicos
  • database-health-check: Avaliação abrangente de saúde do banco de dados e recomendações
  • index-recommendation: Obtenha sugestões personalizadas de índices com base em padrões de consulta
  • migration-guide: Planos passo a passo de migração de versão do MongoDB
  • mongo-shell: Gerar comandos de shell do MongoDB com explicações
  • multi-tenant-design: Projetar arquitetura de banco de dados multi-tenant no MongoDB
  • query-builder: Orientação interativa para construir consultas MongoDB
  • query-optimizer: Recomendações de otimização para consultas lentas
  • schema-analysis: Análise detalhada de esquema de coleções com recomendações
  • schema-versioning: Gerenciar evolução de esquemas em aplicações MongoDB
  • security-audit: Análise de segurança do banco de dados e recomendações de melhoria
  • sql-to-mongodb: Converter consultas SQL em pipelines de agregação MongoDB

Outros Recursos

Outros Recursos: Visão Geral

O MongoDB Lens inclui diversos outros recursos:

  • Arquivo de Configuração: Configuração personalizada via ~/.mongodb-lens.[jsonc|json]
  • Substituições por Variáveis de Ambiente: Substituir configurações via process.env.CONFIG_*
  • Sistema de Confirmação: Verificação em duas etapas para operações destrutivas
  • Múltiplas Conexões: Definir e alternar entre aliases de URI nomeados
  • Desativação de Componentes: Desativar seletivamente ferramentas, prompts ou recursos
  • Resiliência de Conexão: Reconexão automática com backoff exponencial
  • Salvaguardas de Consulta: Limites configuráveis e proteções de desempenho
  • Tratamento de Erros: Códigos e mensagens de erro JSONRPC abrangentes
  • Inferência de Esquema: Análise eficiente de esquemas com amostragem inteligente
  • Proteção de Credenciais: Ofuscação de senhas em strings de conexão nos logs
  • Gerenciamento de Memória: Monitoramento e limpeza automáticos para operações grandes
  • Cache Inteligente: Cache otimizado para esquemas, índices, campos e coleções
  • Compatibilidade Retroativa: Suporte a versões modernas e legadas do MongoDB

Outros Recursos: Novos Metadados de Banco de Dados

O MongoDB Lens insere uma coleção metadata em cada banco de dados que cria.

Esta coleção metadata armazena um único documento contendo informações contextuais que servem como registro permanente da origem do banco de dados, garantindo ao mesmo tempo que o banco de dados novo e de outra forma vazio persista no sistema de armazenamento do MongoDB.

Exemplo de documento de metadados 
{
    "_id" : ObjectId("67d5284463788ec38aecee14"),
    "created" : {
        "timestamp" : ISODate("2025-03-15T07:12:04.705Z"),
        "tool" : "MongoDB Lens v5.0.7",
        "user" : "anonymous"
    },
    "mongodb" : {
        "version" : "3.6.23",
        "connectionInfo" : {
            "host" : "unknown",
            "readPreference" : "primary"
        }
    },
    "database" : {
        "name" : "example_database",
        "description" : "Created via MongoDB Lens"
    },
    "system" : {
        "hostname" : "unknown",
        "platform" : "darwin",
        "nodeVersion" : "v22.14.0"
    },
    "lens" : {
        "version" : "5.0.7",
        "startTimestamp" : ISODate("2025-03-15T07:10:06.084Z")
    }
}

Depois de adicionar suas próprias coleções ao novo banco de dados, você pode remover com segurança a coleção metadata usando a ferramenta drop-collection:

  • "Excluir a coleção de metadados do novo banco de dados"
    ➥ Usa a ferramenta drop-collection (com confirmação)

Instalação

O MongoDB Lens pode ser instalado e executado de várias maneiras:

Instalação: NPX

[!NOTE]
NPX requer Node.js instalado e em execução no seu sistema (sugestão: use Volta).

A maneira mais fácil de executar o MongoDB Lens é usando NPX.

Primeiro, certifique-se de que o Node.js está instalado:

node --version # Ideally >= v22.x but MongoDB Lens is >= v18.x compatible

Em seguida, execute o MongoDB Lens via NPX:

# Using default connection string mongodb://localhost:27017
npx -y mongodb-lens

# Using custom connection string
npx -y mongodb-lens mongodb://your-connection-string

# Using "@latest" to keep the package up-to-date
npx -y mongodb-lens@latest

[!TIP]
Se você encontrar erros de permissão com npx, tente executar npx clear-npx-cache antes de executar npx -y mongodb-lens (isso limpa o cache e baixa novamente o pacote).

Instalação: Docker Hub

[!NOTE]
Docker Hub requer Docker instalado e em execução no seu sistema.

Primeiro, certifique-se de que o Docker está instalado:

docker --version # Ideally >= v27.x

Em seguida, execute o MongoDB Lens via Docker Hub:

# Using default connection string mongodb://localhost:27017
docker run --rm -i --network=host furey/mongodb-lens

# Using custom connection string
docker run --rm -i --network=host furey/mongodb-lens mongodb://your-connection-string

# Using "--pull" to keep the Docker image up-to-date
docker run --rm -i --network=host --pull=always furey/mongodb-lens

Instalação: Node.js a partir do Código Fonte

[!NOTE]
Node.js a partir do código fonte requer Node.js instalado e em execução no seu sistema (sugestão: use Volta).

  1. Clone o repositório do MongoDB Lens:
    git clone https://github.com/furey/mongodb-lens.git
  2. Navegue até o diretório do repositório clonado:
    cd /path/to/mongodb-lens
  3. Certifique-se de que o Node.js está instalado:
    node --version # Ideally >= v22.x but MongoDB Lens is >= v18.x compatible
  4. Instale as dependências do Node.js:
    npm ci
  5. Inicie o servidor:
    # Using default connection string mongodb://localhost:27017
node mongodb-lens.js

# Using custom connection string
node mongodb-lens.js mongodb://your-connection-string

Instalação: Docker a partir do Código Fonte

[!NOTE]
Docker a partir do código fonte requer Docker instalado e em execução no seu sistema.

  1. Clone o repositório do MongoDB Lens:
    git clone https://github.com/furey/mongodb-lens.git
  2. Navegue até o diretório do repositório clonado:
    cd /path/to/mongodb-lens
  3. Certifique-se de que o Docker está instalado:
    docker --version # Ideally >= v27.x
  4. Construa a imagem Docker:
    docker build -t mongodb-lens .
  5. Execute o contêiner:
    # Using default connection string mongodb://localhost:27017
docker run --rm -i --network=host mongodb-lens

# Using custom connection string
docker run --rm -i --network=host mongodb-lens mongodb://your-connection-string

Verificação da Instalação

Para verificar a instalação, cole e execute a seguinte mensagem JSONRPC no stdio do servidor:

{"method":"resources/read","params":{"uri":"mongodb://databases"},"jsonrpc":"2.0","id":1}

O servidor deve responder com uma lista de bancos de dados na sua instância MongoDB, por exemplo:

{"result":{"contents":[{"uri":"mongodb://databases","text":"Databases (12):\n- admin (180.00 KB)\n- config (108.00 KB)\n- local (40.00 KB)\n- sample_airbnb (51.88 MB)\n- sample_analytics (9.46 MB)\n- sample_geospatial (980.00 KB)\n- sample_guides (40.00 KB)\n- sample_mflix (108.90 MB)\n- sample_restaurants (7.73 MB)\n- sample_supplies (968.00 KB)\n- sample_training (40.85 MB)\n- sample_weatherdata (2.69 MB)"}]},"jsonrpc":"2.0","id":1}

O MongoDB Lens agora está instalado e pronto para aceitar solicitações MCP.

Instalação: Versões Antigas do MongoDB

Se você estiver se conectando a uma instância MongoDB com uma versão < 4.0, o driver Node.js do MongoDB usado pela versão mais recente do MongoDB Lens não será compatível. Especificamente, versões 4.0.0 e superiores do driver Node.js do MongoDB exigem a versão 4.0 ou superior do MongoDB.

Para usar o MongoDB Lens com instâncias MongoDB mais antigas, você precisa usar uma versão do driver Node.js do MongoDB da série 3.x (por exemplo, 3.7.4, que é compatível com MongoDB 3.6).

Versões Antigas do MongoDB: Executando a Partir do Código-Fonte

  1. Clone o repositório do MongoDB Lens:
    git clone https://github.com/furey/mongodb-lens.git
  2. Navegue até o diretório do repositório clonado:
    cd /path/to/mongodb-lens
  3. Modifique o package.json:
    "dependencies": {
  ...
-  "mongodb": "^6.15.0",  // Or whatever newer version is listed
+  "mongodb": "^3.7.4",   // Or whatever 3.x version is compatible with your older MongoDB instance
  ...
}
  4. Instale as dependências do Node.js:
    npm install
  5. Inicie o MongoDB Lens:
    node mongodb-lens.js mongodb://older-mongodb-instance

Isso usará a versão mais antiga do driver compatível com sua instância MongoDB.

[!NOTE]
Talvez você também precise reverter este commit para adicionar novamente as opções de configuração do MongoDB useNewUrlParser e useUnifiedTopology.

Versões Antigas do MongoDB: Usando NPX ou Docker

Se você preferir usar NPX ou Docker, precisará usar uma versão mais antiga do MongoDB Lens que foi publicada com um driver compatível.

Por exemplo, o MongoDB Lens 8.3.0 usa o driver Node.js do MongoDB 3.7.4 (veja: package-lock.json).

Para executar uma versão mais antiga do MongoDB Lens usando NPX, especifique a tag de versão:

npx -y mongodb-lens@8.3.0

Da mesma forma para Docker:

docker run --rm -i --network=host furey/mongodb-lens:8.3.0

Configuração

Configuração: String de Conexão MongoDB

O servidor aceita uma string de conexão MongoDB como seu único argumento.

Exemplo de uso com NPX:

npx -y mongodb-lens@latest mongodb://your-connection-string

As strings de conexão MongoDB têm o seguinte formato:

mongodb://[username:password@]host[:port][/database][?options]

Exemplos de strings de conexão:

  • Conexão local:
    mongodb://localhost:27017
  • Conexão ao mydatabase com credenciais do banco de dados admin:
    mongodb://username:password@hostname:27017/mydatabase?authSource=admin
  • Conexão ao mydatabase com várias outras opções:
    mongodb://hostname:27017/mydatabase?retryWrites=true&w=majority

Se nenhuma string de conexão for fornecida, o servidor tentará se conectar via conexão local.

Configuração: Arquivo de Configuração

O MongoDB Lens suporta ampla personalização por meio de arquivo de configuração JSON.

[!NOTE]
O arquivo de configuração é opcional. O MongoDB Lens será executado com as configurações padrão se nenhum arquivo de configuração for fornecido.

[!TIP]
Você só precisa incluir as configurações que deseja personalizar no arquivo de configuração. O MongoDB Lens usará as configurações padrão para qualquer valor omitido.

[!TIP]
O MongoDB Lens suporta formatos de arquivo de configuração .json e .jsonc (JSON com comentários).

Exemplo de arquivo de configuração 
{
  "mongoUri": "mongodb://localhost:27017",         // Default MongoDB connection string or object of alias-URI pairs
  "connectionOptions": {
    "maxPoolSize": 20,                             // Maximum number of connections in the pool
    "retryWrites": false,                          // Whether to retry write operations
    "connectTimeoutMS": 30000,                     // Connection timeout in milliseconds
    "socketTimeoutMS": 360000,                     // Socket timeout in milliseconds
    "heartbeatFrequencyMS": 10000,                 // How often to ping servers for status
    "serverSelectionTimeoutMS": 30000              // Timeout for server selection
  },
  "defaultDbName": "admin",                        // Default database if not specified in URI
  "connection": {
    "maxRetries": 5,                               // Maximum number of initial connection attempts
    "maxRetryDelayMs": 30000,                      // Maximum delay between retries
    "reconnectionRetries": 10,                     // Maximum reconnection attempts if connection lost
    "initialRetryDelayMs": 1000                    // Initial delay between retries
  },
  "disabled": {
    "tools": [],                                   // Array of tools to disable or true to disable all
    "prompts": [],                                 // Array of prompts to disable or true to disable all
    "resources": []                                // Array of resources to disable or true to disable all
  },
  "enabled": {
    "tools": true,                                 // Array of tools to enable or true to enable all
    "prompts": true,                               // Array of prompts to enable or true to enable all
    "resources": true                              // Array of resources to enable or true to enable all
  },
  "cacheTTL": {
    "stats": 15000,                                // Stats cache lifetime in milliseconds
    "fields": 30000,                               // Fields cache lifetime in milliseconds
    "schemas": 60000,                              // Schema cache lifetime in milliseconds
    "indexes": 120000,                             // Index cache lifetime in milliseconds
    "collections": 30000,                          // Collections list cache lifetime in milliseconds
    "serverStatus": 20000                          // Server status cache lifetime in milliseconds
  },
  "enabledCaches": [                               // List of caches to enable
    "stats",                                       // Statistics cache
    "fields",                                      // Collection fields cache
    "schemas",                                     // Collection schemas cache
    "indexes",                                     // Collection indexes cache
    "collections",                                 // Database collections cache
    "serverStatus"                                 // MongoDB server status cache
  ],
  "memory": {
    "enableGC": true,                              // Whether to enable garbage collection
    "warningThresholdMB": 1500,                    // Memory threshold for warnings
    "criticalThresholdMB": 2000                    // Memory threshold for cache clearing
  },
  "logLevel": "info",                              // Log level (info or verbose)
  "disableDestructiveOperationTokens": false,      // Whether to skip confirmation for destructive ops
  "watchdogIntervalMs": 30000,                     // Interval for connection monitoring
  "defaults": {
    "slowMs": 100,                                 // Threshold for slow query detection
    "queryLimit": 10,                              // Default limit for query results
    "allowDiskUse": true,                          // Allow operations to use disk for large datasets
    "schemaSampleSize": 100,                       // Sample size for schema inference
    "aggregationBatchSize": 50                     // Batch size for aggregation operations
  },
  "security": {
    "tokenLength": 4,                              // Length of confirmation tokens
    "tokenExpirationMinutes": 5,                   // Expiration time for tokens
    "strictDatabaseNameValidation": true           // Enforce strict database name validation
  },
  "tools": {
    "transaction": {
      "readConcern": "snapshot",                   // Read concern level for transactions
      "writeConcern": {
        "w": "majority"                            // Write concern for transactions
      }
    },
    "bulkOperations": {
      "ordered": true                              // Whether bulk operations execute in order
    },
    "export": {
      "defaultLimit": -1,                          // Default limit for exports (-1 = no limit)
      "defaultFormat": "json"                      // Default export format (json or csv)
    },
    "watchChanges": {
      "maxDurationSeconds": 60,                    // Maximum duration for change streams
      "defaultDurationSeconds": 10                 // Default duration for change streams
    },
    "queryAnalysis": {
      "defaultDurationSeconds": 10                 // Default duration for query analysis
    }
  }
}

Por padrão, o MongoDB Lens procura o arquivo de configuração em:

  • ~/.mongodb-lens.jsonc primeiro e, em seguida, volta para
  • ~/.mongodb-lens.json se o primeiro não existir

Para personalizar o caminho do arquivo de configuração, defina a variável de ambiente CONFIG_PATH para o caminho do arquivo desejado.

Exemplo de uso com NPX:

CONFIG_PATH='/path/to/config.json' npx -y mongodb-lens@latest

Exemplo de uso com Docker Hub:

docker run --rm -i --network=host --pull=always -v /path/to/config.json:/root/.mongodb-lens.json furey/mongodb-lens

Configuração: Geração do Arquivo de Configuração

Você pode gerar um arquivo de configuração automaticamente usando o script config:create:

# NPX Usage (recommended)
npx -y mongodb-lens@latest config:create

# Node.js Usage
npm run config:create

# Force overwrite existing files
npx -y mongodb-lens@latest config:create -- --force
npm run config:create -- --force

Este script extrai o arquivo de configuração de exemplo acima e o salva em: ~/.mongodb-lens.jsonc

Geração do Arquivo de Configuração: Caminho Personalizado

Você pode especificar um local de saída personalizado usando a variável de ambiente CONFIG_PATH.

  • Se CONFIG_PATH não tiver extensão de arquivo, será tratado como um diretório e .mongodb-lens.jsonc será anexado
  • Se CONFIG_PATH terminar com .json (não .jsonc), os comentários serão removidos do arquivo gerado

Exemplo de uso com NPX:

# With custom path
CONFIG_PATH=/path/to/config.jsonc npx -y mongodb-lens@latest config:create

# Save to directory (will append .mongodb-lens.jsonc to the path)
CONFIG_PATH=/path/to/directory npx -y mongodb-lens@latest config:create

# Save as JSON instead of JSONC
CONFIG_PATH=/path/to/config.json npx -y mongodb-lens@latest config:create

Exemplo de uso com Node.js:

# With custom path
CONFIG_PATH=/path/to/config.jsonc node mongodb-lens.js config:create

# Save to directory (will append .mongodb-lens.jsonc to the path)
CONFIG_PATH=/path/to/directory node mongodb-lens.js config:create

# Save as JSON instead of JSONC
CONFIG_PATH=/path/to/config.json node mongodb-lens.js config:create

Configuração: Múltiplas Conexões MongoDB

O MongoDB Lens suporta múltiplas URIs MongoDB com aliases no seu arquivo de configuração, permitindo que você alterne facilmente entre diferentes instâncias MongoDB usando nomes simples.

Para configurar múltiplas conexões, defina a configuração mongoUri como um objeto com pares alias-URI:

{
  "mongoUri": {
    "main": "mongodb://localhost:27017",
    "backup": "mongodb://localhost:27018",
    "atlas": "mongodb+srv://username:password@cluster.mongodb.net/mydb"
  }
}

Com esta configuração:

  • A primeira URI na lista (por exemplo, main) torna-se a conexão padrão na inicialização
  • Você pode alternar conexões usando linguagem natural: "Connect to backup" ou "Connect to atlas"
  • A sintaxe original ainda funciona: "Connect to mongodb://localhost:27018"
  • A ferramenta list-connections mostra todos os aliases de conexão disponíveis

[!NOTE]
Ao usar o argumento de linha de comando para especificar uma conexão, você pode usar uma URI MongoDB completa ou um alias definido no seu arquivo de configuração.

[!TIP]
Para adicionar aliases de conexão em tempo de execução, use a ferramenta add-connection-alias.

Configuração: Substituições por Variáveis de Ambiente

O MongoDB Lens suporta substituições por variáveis de ambiente para configurações.

As variáveis de ambiente têm precedência sobre as configurações do arquivo de configuração.

As variáveis de ambiente de configuração seguem o padrão de nomenclatura:

CONFIG_[SETTING PATH, SNAKE CASED, UPPERCASED]

Exemplos de substituições:

ConfiguraçãoSubstituição por Variável de Ambiente
mongoUriCONFIG_MONGO_URI
logLevelCONFIG_LOG_LEVEL
defaultDbNameCONFIG_DEFAULT_DB_NAME
defaults.queryLimitCONFIG_DEFAULTS_QUERY_LIMIT
tools.export.defaultFormatCONFIG_TOOLS_EXPORT_DEFAULT_FORMAT
connectionOptions.maxPoolSizeCONFIG_CONNECTION_OPTIONS_MAX_POOL_SIZE
connection.reconnectionRetriesCONFIG_CONNECTION_RECONNECTION_RETRIES

Para valores de variáveis de ambiente:

  • Para configurações booleanas, use valores de string 'true' ou 'false'.
  • Para configurações numéricas, use representações de string.
  • Para objetos aninhados ou arrays, use strings JSON.

Exemplo de uso com NPX:

CONFIG_DEFAULTS_QUERY_LIMIT='25' npx -y mongodb-lens@latest

Exemplo de uso com Docker Hub:

docker run --rm -i --network=host --pull=always -e CONFIG_DEFAULTS_QUERY_LIMIT='25' furey/mongodb-lens

Configuração: Variáveis de Ambiente Multiplataforma

Para uso consistente de variáveis de ambiente no Windows, macOS e Linux, considere usar cross-env:

  1. Instale o cross-env globalmente:
    # Using NPM
npm install -g cross-env

# Using Volta (see: https://volta.sh)
volta install cross-env
  2. Prefixe qualquer variável de ambiente NPX ou Node.js nos exemplos deste documento:
    # Example NPX usage with cross-env
cross-env CONFIG_DEFAULTS_QUERY_LIMIT='25' npx -y mongodb-lens@latest

# Example Node.js usage with cross-env
cross-env CONFIG_DEFAULTS_QUERY_LIMIT='25' node mongodb-lens.js

Configuração do Cliente

Configuração do Cliente: Claude Desktop

Para usar o MongoDB Lens com o Claude Desktop:

  1. Instale o Claude Desktop
  2. Abra claude_desktop_config.json (crie se não existir):
    • macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
    • Windows: %APPDATA%\Claude\claude_desktop_config.json
  3. Adicione a configuração do servidor MongoDB Lens conforme as opções de configuração
  4. Reinicie o Claude Desktop
  5. Inicie uma conversa com o Claude sobre seus dados MongoDB

Opções de Configuração do Claude Desktop

Para cada opção:

  • Substitua mongodb://your-connection-string pela sua string de conexão MongoDB ou omita-a para usar o padrão mongodb://localhost:27017.
  • Para usar um arquivo de configuração personalizado, defina a variável de ambiente CONFIG_PATH.
  • Para incluir variáveis de ambiente:
    • Para NPX ou Node.js, adicione "env": {} com pares chave-valor, por exemplo:
      "command": "/path/to/npx",
"args": [
  "-y",
  "mongodb-lens@latest",
  "mongodb://your-connection-string"
],
"env": {
  "CONFIG_LOG_LEVEL": "verbose"
}
    • Para Docker, adicione flags -e, por exemplo:
      "command": "docker",
"args": [
  "run", "--rm", "-i",
  "--network=host",
  "--pull=always",
  "-e", "CONFIG_LOG_LEVEL=verbose",
  "furey/mongodb-lens",
  "mongodb://your-connection-string"
]
Opção 1: NPX (Recomendado)
{
  "mcpServers": {
    "mongodb-lens": {
      "command": "/path/to/npx",
      "args": [
        "-y",
        "mongodb-lens@latest",
        "mongodb://your-connection-string"
      ]
    }
  }
}
Opção 2: Imagem Docker Hub
{
  "mcpServers": {
    "mongodb-lens": {
      "command": "docker",
      "args": [
        "run", "--rm", "-i",
        "--network=host",
        "--pull=always",
        "furey/mongodb-lens",
        "mongodb://your-connection-string"
      ]
    }
  }
}
Opção 3: Instalação Local do Node.js
{
  "mcpServers": {
    "mongodb-lens": {
      "command": "/path/to/node",
      "args": [
        "/path/to/mongodb-lens.js",
        "mongodb://your-connection-string"
      ]
    }
  }
}
Opção 4: Imagem Docker Local
{
  "mcpServers": {
    "mongodb-lens": {
      "command": "docker",
      "args": [
        "run", "--rm", "-i",
        "--network=host",
        "mongodb-lens",
        "mongodb://your-connection-string"
      ]
    }
  }
}

Configuração do Cliente: MCP Inspector

O MCP Inspector é uma ferramenta projetada para testar e depurar servidores MCP.

[!NOTE]
O MCP Inspector inicia um servidor proxy na porta 3000 e um cliente web na porta 5173.

Exemplo de uso com NPX:

  1. Execute o MCP Inspector:
    # Using default connection string mongodb://localhost:27017
npx -y @modelcontextprotocol/inspector npx -y mongodb-lens@latest

# Using custom connection string
npx -y @modelcontextprotocol/inspector npx -y mongodb-lens@latest mongodb://your-connection-string

# Using custom ports
SERVER_PORT=1234 CLIENT_PORT=5678 npx -y @modelcontextprotocol/inspector npx -y mongodb-lens@latest
  2. Abra o MCP Inspector: http://localhost:5173

O MCP Inspector deve suportar toda a gama de recursos do MongoDB Lens, incluindo autocompletar para nomes de coleções e campos de consulta.

Para mais informações, veja: MCP Inspector

Configuração do Cliente: Outros Clientes MCP

O MongoDB Lens deve ser utilizável com qualquer cliente compatível com MCP.

Para mais informações, veja: Documentação MCP: Exemplos de Clientes

Proteção de Dados

Para proteger seus dados ao usar o MongoDB Lens, considere o seguinte:

Proteção de Dados: Contas de Usuário Somente Leitura

Ao conectar o MongoDB Lens ao seu banco de dados, as permissões concedidas ao usuário na string de conexão MongoDB determinam quais ações podem ser executadas. Quando o caso de uso se adequar, um usuário somente leitura pode prevenir gravações ou exclusões não intencionais, garantindo que o MongoDB Lens possa consultar dados, mas não alterá-los.

Para configurar isso, crie um usuário com a função read no(s) banco(s) de dados que você está segmentando. No shell do MongoDB, você executaria algo como:

use admin

db.createUser({
  user: 'readonly',
  pwd: 'eXaMpLePaSsWoRd',
  roles: [{ role: 'read', db: 'mydatabase' }]
})

Em seguida, aplique essas credenciais à sua string de conexão MongoDB:

mongodb://readonly:eXaMpLePaSsWoRd@localhost:27017/mydatabase

Usar credenciais somente leitura é uma maneira simples, porém eficaz, de impor limites de segurança, especialmente quando você está explorando esquemas ou executando consultas ad-hoc.

Proteção de Dados: Trabalhando com Backups de Banco de Dados

Ao trabalhar com o MongoDB Lens, considere conectar-se a uma cópia de backup dos seus dados hospedada em uma instância MongoDB separada.

Comece gerando o backup com mongodump. Em seguida, inicie uma nova instância MongoDB (por exemplo, em uma porta diferente, como 27018) e restaure o backup lá usando mongorestore. Depois que estiver em execução, aponte o MongoDB Lens para a string de conexão da instância de backup (por exemplo, mongodb://localhost:27018/mydatabase).

Essa abordagem oferece um ambiente de testes para testar operações complexas ou destrutivas sem arriscar corrupção acidental dos seus dados em produção.

Proteção de Dados: Considerações sobre Fluxo de Dados

Considerações sobre Fluxo de Dados: Como Seus Dados Fluem pelo Sistema

Ao usar um Servidor MCP com um provedor de LLM remoto (como Anthropic via Claude Desktop), entender como seus dados fluem pelo sistema é fundamental para proteger informações sensíveis de exposição não intencional.

Quando você envia uma consulta relacionada ao MongoDB através do seu cliente MCP, aqui está o que acontece:

[!NOTE]
Embora este exemplo use uma instância MongoDB local, os mesmos princípios se aplicam a instâncias MongoDB remotas.

sequenceDiagram
    actor User
    box Local Machine #d4f1f9
        participant Client as MCP Client
        participant Lens as MongoDB Lens
        participant MongoDB as MongoDB Instance
    end
    box Remote Server #ffe6cc
        participant LLM as Remote LLM Provider
    end

    User->>Client: 1. Submit request<br>"Show me all users older than 30"
    Client->>LLM: 2. User request + available tools
    Note over LLM: Interprets request<br>Chooses appropriate tool
    LLM->>Client: 3. Tool selection (find-documents)
    Client->>Lens: 4. Tool run with parameters
    Lens->>MongoDB: 5. Database query
    MongoDB-->>Lens: 6. Database results
    Lens-->>Client: 7. Tool results (formatted data)
    Client->>LLM: 8. Tool results
    Note over LLM: Processes results<br>Formats response
    LLM-->>Client: 9. Processed response
    Client-->>User: 10. Final answer
  1. Você envia uma solicitação
    ➥ ex.: "Mostre-me todos os usuários com mais de 30 anos"
  2. Seu cliente envia a solicitação ao LLM remoto
    ➥ O provedor de LLM recebe suas palavras exatas juntamente com uma lista de ferramentas MCP disponíveis e seus parâmetros.
  3. O LLM remoto interpreta sua solicitação
    ➥ Ele determina sua intenção e instrui o cliente a usar uma ferramenta MCP específica com os parâmetros apropriados.
  4. O cliente pede ao MongoDB Lens para executar a ferramenta
    ➥ Isso ocorre localmente na sua máquina via stdio.
  5. O MongoDB Lens consulta seu banco de dados MongoDB
  6. O MongoDB Lens recupera os resultados da sua consulta MongoDB
  7. O MongoDB Lens envia os dados de volta ao cliente
    ➥ O cliente recebe os resultados formatados pelo MongoDB Lens.
  8. O cliente encaminha os dados ao LLM remoto
    ➥ O provedor de LLM vê os dados exatos retornados pelo MongoDB Lens.
  9. O LLM remoto processa os dados
    ➥ Ele pode resumir ou formatar ainda mais os resultados.
  10. O LLM remoto envia a resposta final ao cliente
    ➥ O cliente exibe a resposta para você.

O provedor de LLM remoto vê tanto sua solicitação original quanto a resposta completa do MongoDB Lens. Se seu banco de dados incluir campos sensíveis (ex.: senhas, dados pessoais, etc.), esses dados podem ser transmitidos involuntariamente ao provedor remoto, a menos que você tome precauções.

Considerações sobre o Fluxo de Dados: Protegendo Dados Sensíveis com Projeção

Para evitar que dados sensíveis sejam enviados ao provedor de LLM remoto, use o conceito de projeção ao utilizar ferramentas como find-documents, aggregate-data ou export-data. A projeção permite especificar quais campos incluir ou excluir nos resultados da consulta, garantindo que informações sensíveis permaneçam locais.

Exemplo de uso de projeção:

  • "Mostre-me todos os usuários com mais de 30 anos, mas use projeção para ocultar suas senhas."
    ➥ Usa a ferramenta find-documents com projeção

Considerações sobre o Fluxo de Dados: Aliases de Conexão e Senhas

Ao adicionar novos aliases de conexão usando a ferramenta add-connection-alias, evite adicionar aliases a URIs que contenham senhas se você estiver usando um provedor de LLM remoto. Como sua solicitação é enviada ao LLM, qualquer senha na URI pode ser exposta. Em vez disso, defina aliases com senhas no arquivo de configuração do MongoDB Lens, onde elas permanecem locais e não são transmitidas ao LLM.

Considerações sobre o Fluxo de Dados: Configuração Local para Máxima Segurança

Embora esteja fora do escopo deste documento, para o mais alto nível de privacidade de dados, considere usar um cliente MCP local emparelhado com um modelo de LLM hospedado localmente. Essa abordagem mantém todas as solicitações e dados dentro do seu ambiente local, eliminando o risco de informações sensíveis serem enviadas a um provedor remoto.

Proteção de Dados: Confirmação para Operações Destrutivas

O MongoDB Lens implementa um sistema de confirmação baseado em token para operações potencialmente destrutivas, exigindo um processo de duas etapas para executar ferramentas que podem resultar em perda de dados não verificada:

  1. Primeira invocação da ferramenta: Retorna um token de confirmação de 4 dígitos que expira após 5 minutos
  2. Segunda invocação da ferramenta: Executa a operação se for fornecida com o token válido

Para um exemplo do processo de confirmação, veja: Trabalhando com Proteção de Confirmação

As ferramentas que exigem confirmação incluem:

  • drop-user: Remover um usuário do banco de dados
  • drop-index: Remover um índice (possível impacto no desempenho)
  • drop-database: Excluir permanentemente um banco de dados
  • drop-collection: Excluir uma coleção e todos os seus documentos
  • delete-document: Excluir um ou vários documentos
  • bulk-operations: Ao incluir operações de exclusão
  • rename-collection: Quando a coleção de destino existe e será descartada

Este mecanismo de proteção visa evitar perda acidental de dados devido a erros de digitação e comandos não intencionais. É uma rede de segurança que garante que você esteja ciente das consequências antes de prosseguir com ações potencialmente prejudiciais.

[!NOTE]
Se você estiver trabalhando em um ambiente controlado onde a perda de dados é aceitável, você pode configurar o MongoDB Lens para ignorar a confirmação e executar operações destrutivas imediatamente.

Ignorando a Confirmação para Operações Destrutivas

Você pode querer ignorar o sistema de confirmação por token.

Defina a variável de ambiente CONFIG_DISABLE_DESTRUCTIVE_OPERATION_TOKENS para true para executar operações destrutivas imediatamente sem confirmação:

# Using NPX
CONFIG_DISABLE_DESTRUCTIVE_OPERATION_TOKENS=true npx -y mongodb-lens@latest

# Using Docker
docker run --rm -i --network=host --pull=always -e CONFIG_DISABLE_DESTRUCTIVE_OPERATION_TOKENS='true' furey/mongodb-lens

[!WARNING]
Desabilitar tokens de confirmação remove um mecanismo de segurança importante. É fortemente recomendado usar esta opção apenas em ambientes controlados onde a perda de dados é aceitável, como desenvolvimento ou testes. Desabilite por sua conta e risco.

Proteção de Dados: Desabilitando Operações Destrutivas

Desabilitando Ferramentas

O MongoDB Lens inclui várias ferramentas que podem modificar ou excluir dados. Para desabilitar ferramentas específicas, adicione-as ao array disabled.tools no seu arquivo de configuração:

{
  "disabled": {
    "tools": [
      "drop-user",
      "drop-index",
      "drop-database",
      "drop-collection",
      "delete-document",
      "bulk-operations",
      "rename-collection"
    ]
  }
}

[!NOTE]
Recursos e prompts também podem ser desabilitados via configurações disabled.resources e disabled.prompts.

Ferramentas de Alto Risco

Estas ferramentas podem causar perda imediata de dados e devem ser consideradas para desabilitação em ambientes sensíveis:

  • drop-user: Remove usuários do banco de dados e suas permissões de acesso
  • drop-index: Remove índices (pode impactar o desempenho de consultas)
  • drop-database: Exclui permanentemente bancos de dados inteiros
  • drop-collection: Exclui permanentemente coleções e todos os seus documentos
  • delete-document: Remove documentos que correspondem a critérios especificados
  • bulk-operations: Pode realizar exclusões em lote quando configurado para isso
  • rename-collection: Pode sobrescrever coleções existentes ao usar a opção de descartar destino

Ferramentas de Risco Médio

Estas ferramentas podem modificar dados, mas normalmente não causam perda imediata de dados:

  • create-user: Cria usuários com permissões que podem permitir outras alterações
  • transaction: Executa múltiplas operações em uma transação (potencial para alterações complexas)
  • update-document: Atualiza documentos que podem sobrescrever dados existentes

Configuração Somente Leitura

Para uma configuração completamente somente leitura, desabilite todas as ferramentas potencialmente destrutivas:

{
  "disabled": {
    "tools": [
      "drop-user",
      "drop-index",
      "create-user",
      "transaction",
      "create-index",
      "drop-database",
      "drop-collection",
      "insert-document",
      "update-document",
      "delete-document",
      "bulk-operations",
      "create-database",
      "gridfs-operation",
      "create-collection",
      "rename-collection",
      "create-timeseries"
    ]
  }
}

Esta configuração permite que o MongoDB Lens consulte e analise dados enquanto previne qualquer modificação, fornecendo múltiplas camadas de proteção contra perda acidental de dados.

Habilitação Seletiva de Componentes

Além de desabilitar componentes, especifique exatamente quais componentes devem ser habilitados (desabilitando implicitamente todos os outros) usando as configurações enabled no seu arquivo de configuração:

{
  "enabled": {
    "tools": [
      "use-database",
      "find-documents",
      "count-documents",
      "aggregate-data"
    ]
  },
  "disabled": {
    "resources": true,
    "prompts": true
  }
}

[!IMPORTANT]
Se um componente aparecer em ambas as listas enabled e disabled, a configuração enabled tem precedência.

Tutorial

O tutorial a seguir guia você pela configuração de um contêiner MongoDB com dados de exemplo e, em seguida, pelo uso do MongoDB Lens para interagir com ele por meio de consultas em linguagem natural:

  1. Iniciar Contêiner de Dados de Exemplo
  2. Importar Dados de Exemplo
  3. Conectar o MongoDB Lens
  4. Consultas de Exemplo
  5. Trabalhando com Proteção de Confirmação

Tutorial: 1. Iniciar Contêiner de Dados de Exemplo

[!NOTE]
Este tutorial pressupõe que você tenha o Docker instalado e em execução no seu sistema.

[!IMPORTANT]
Se o Docker já estiver executando um contêiner na porta 27017, pare-o antes de prosseguir.

  1. Inicialize o contêiner de dados de exemplo:
    docker run --name mongodb-sampledata -d -p 27017:27017 mongo:6
  2. Verifique se o contêiner está em execução sem problemas:
    docker ps | grep mongodb-sampledata

Tutorial: 2. Importar Dados de Exemplo

O MongoDB fornece vários conjuntos de dados de exemplo que usaremos para explorar o MongoDB Lens.

  1. Baixe os conjuntos de dados de exemplo: 
    curl -LO https://atlas-education.s3.amazonaws.com/sampledata.archive
  2. Copie os conjuntos de dados de exemplo para o seu contêiner de dados de exemplo:
    docker cp sampledata.archive mongodb-sampledata:/tmp/
  3. Importe os conjuntos de dados de exemplo para o MongoDB:
    docker exec -it mongodb-sampledata mongorestore --archive=/tmp/sampledata.archive

Isso importará vários bancos de dados:

  • sample_airbnb: Listagens e avaliações do Airbnb
  • sample_analytics: Dados de clientes e contas
  • sample_geospatial: Dados geográficos
  • sample_mflix: Dados de filmes
  • sample_restaurants: Dados de restaurantes
  • sample_supplies: Dados da cadeia de suprimentos
  • sample_training: Dados de treinamento para várias aplicações
  • sample_weatherdata: Medições meteorológicas

Tutorial: 3. Conectar o MongoDB Lens

Instale o MongoDB Lens conforme as instruções do Início Rápido.

Configure seu Cliente MCP para conectar ao MongoDB Lens via: mongodb://localhost:27017

[!TIP]
Omitir a string de conexão da configuração do seu Cliente MCP fará com que a string de conexão padrão seja mongodb://localhost:27017.

Exemplo de configuração do Claude Desktop:

{
  "mcpServers": {
    "mongodb-lens": {
      "command": "/path/to/npx",
      "args": [
        "-y",
        "mongodb-lens@latest"
      ]
    }
  }
}

Tutorial: 4. Consultas de Exemplo

Com seu Cliente MCP em execução e conectado ao MongoDB Lens, tente as seguintes consultas de exemplo:

Consultas de Exemplo: Operações Básicas de Banco de Dados

  • "Liste todos os bancos de dados"
    ➥ Usa a ferramenta list-databases
  • "Qual banco de dados estou usando atualmente?"
    ➥ Usa a ferramenta current-database
  • "Mude para o banco de dados sample_mflix"
    ➥ Usa a ferramenta use-database
  • "Crie um novo banco de dados chamado test_db"
    ➥ Usa a ferramenta create-database
  • "Crie outro banco de dados chamado analytics_db e mude para ele"
    ➥ Usa a ferramenta create-database com switch=true
  • "Remova test_db"
    ➥ Usa a ferramenta drop-database (com confirmação)

Consultas de Exemplo: Gerenciamento de Coleções

  • "Quais coleções estão no banco de dados atual?"
    ➥ Usa a ferramenta list-collections
  • "Crie a coleção user_logs"
    ➥ Usa a ferramenta create-collection
  • "Renomeie user_logs para system_logs"
    ➥ Usa a ferramenta rename-collection
  • "Remova system_logs"
    ➥ Usa a ferramenta drop-collection (com confirmação)
  • "Verifique a consistência dos dados na coleção movies"
    ➥ Usa a ferramenta validate-collection

Consultas de Exemplo: Gerenciamento de Usuários

  • "Criar um usuário somente leitura para analytics"
    ➥ Usa a ferramenta create-user
  • "Remover a conta inactive_user"
    ➥ Usa a ferramenta drop-user (com confirmação)

Exemplos de Consultas: Consulta de Dados

  • "Contar todos os documentos na coleção movies"
    ➥ Usa a ferramenta count-documents
  • "Encontrar os 5 melhores filmes com a maior classificação IMDB"
    ➥ Usa a ferramenta find-documents
  • "Mostrar dados agregados para filmes agrupados por década"
    ➥ Usa a ferramenta aggregate-data
  • "Listar todos os países únicos onde os filmes foram produzidos"
    ➥ Usa a ferramenta distinct-values
  • "Buscar filmes contendo godfather no título"
    ➥ Usa a ferramenta text-search
  • "Encontrar usuários alemães com sobrenome müller usando collation adequada"
    ➥ Usa a ferramenta collation-query

Exemplos de Consultas: Análise de Esquema

  • "Qual é a estrutura do esquema da coleção movies?"
    ➥ Usa a ferramenta analyze-schema
  • "Comparar esquemas de users e comments"
    ➥ Usa a ferramenta compare-schemas
  • "Gerar um validador de esquema para a coleção movies"
    ➥ Usa a ferramenta generate-schema-validator
  • "Analisar padrões comuns de consulta para a coleção movies"
    ➥ Usa a ferramenta analyze-query-patterns

Exemplos de Consultas: Modificação de Dados

  • "Inserir novo documento de filme: <your field data>"
    ➥ Usa a ferramenta insert-document
  • "Atualizar todos os filmes de 1994 para adicionar um marcador 'classic'"
    ➥ Usa a ferramenta update-document
  • "Excluir todos os filmes com zero avaliações"
    ➥ Usa a ferramenta delete-document (com confirmação)
  • "Executar estas operações em lote na coleção movies: <your JSON data>"
    ➥ Usa a ferramenta bulk-operations

[!TIP]
Para operações especializadas do MongoDB (como operações de array, operações bit a bit ou outras atualizações complexas), use os operadores nativos do MongoDB por meio dos parâmetros update e options da ferramenta update-document.

Exemplos de Consultas: Gerenciamento de Desempenho e Índices

  • "Criar um índice no campo title na coleção movies"
    ➥ Usa a ferramenta create-index
  • "Remover o índice ratings_idx"
    ➥ Usa a ferramenta drop-index (com confirmação)
  • "Explicar o plano de execução para encontrar filmes de 1995"
    ➥ Usa a ferramenta explain-query
  • "Obter estatísticas para o banco de dados atual"
    ➥ Usa a ferramenta get-stats com target=database
  • "Mostrar estatísticas da coleção para a coleção movies"
    ➥ Usa a ferramenta get-stats com target=collection

Exemplos de Consultas: Operações Geoespaciais e Especiais

  • "Alternar para o banco de dados sample_geospatial e encontrar todos os naufrágios em um raio de 10 km das coordenadas [-80.12, 26.46]"
    ➥ Usa a ferramenta geo-query
  • "Alternar para o banco de dados sample_analytics e executar uma transação para transferir fundos entre contas: <account ids>"
    ➥ Usa a ferramenta transaction
  • "Criar uma coleção de séries temporais para leituras de sensores"
    ➥ Usa a ferramenta create-timeseries
  • "Observar mudanças na coleção users por 30 segundos"
    ➥ Usa a ferramenta watch-changes
  • "Listar todos os arquivos no bucket GridFS images"
    ➥ Usa a ferramenta gridfs-operation com operation=list

Exemplos de Consultas: Exportação, Administração e Outros Recursos

  • "Alternar para o banco de dados sample_mflix e exportar os 20 melhores filmes com base em 'tomatoes.critic.rating' como CSV com os campos title, year e rating (saída em um único bloco de código)"
    ➥ Usa a ferramenta export-data
  • "Alternar para o banco de dados sample_analytics e verificar o status de sharding"
    ➥ Usa a ferramenta shard-status
  • "Limpar o cache de coleções"
    ➥ Usa a ferramenta clear-cache com target=collections
  • "Limpar todos os caches"
    ➥ Usa a ferramenta clear-cache
  • "Alternar para o banco de dados sample_weatherdata e gerar um relatório interativo sobre seu estado atual"
    ➥ Usa várias ferramentas

Exemplos de Consultas: Gerenciamento de Conexão

  • "Conectar a mongodb://localhost:27018"
    ➥ Usa a ferramenta connect-mongodb
  • "Conectar a mongodb+srv://username:password@cluster.mongodb.net/mydb"
    ➥ Usa a ferramenta connect-mongodb
  • "Conectar de volta à instância mongodb original"
    ➥ Usa a ferramenta connect-original
  • "Conectar ao conjunto de réplicas sem validar a conexão: <replica set details>"
    ➥ Usa a ferramenta connect-mongodb com validateConnection=false
  • "Adicionar alias de conexão 'prod' para mongodb://username:password@prod-server:27017/mydb"
    ➥ Usa a ferramenta add-connection-alias

Tutorial: 5. Trabalhando com Proteção de Confirmação

O MongoDB Lens inclui um mecanismo de segurança para operações potencialmente destrutivas. Veja como funciona na prática:

  1. Solicitar a exclusão de uma coleção:
    "Drop the collection named test_collection"
  2. O MongoDB Lens responde com um aviso e um token de confirmação:
    ⚠️ DESTRUCTIVE OPERATION WARNING ⚠️

You've requested to drop the collection 'test_collection'.

This operation is irreversible and will permanently delete all data in this collection.

To confirm, you must type the 4-digit confirmation code EXACTLY as shown below:

Confirmation code: 9876

This code will expire in 5 minutes for security purposes.
  3. Confirmar a operação enviando o token de confirmação:
    "9876"
  4. O MongoDB Lens executa a operação:
    Collection 'test_collection' has been permanently deleted.

Esse processo em duas etapas evita perda acidental de dados ao exigir confirmação explícita.

[!NOTE]
Se você estiver trabalhando em um ambiente controlado onde a perda de dados é aceitável, você pode configurar o MongoDB Lens para ignorar a confirmação e executar operações destrutivas imediatamente.

Suíte de Testes

O MongoDB Lens inclui uma suíte de testes para verificar a funcionalidade em ferramentas, recursos e prompts.

Suíte de Testes: Executando Testes

A suíte de testes requer uma variável de ambiente CONFIG_MONGO_URI que pode ser definida como:

  • uma string de conexão do MongoDB (ex.: mongodb://localhost:27017)
  • mongodb-memory-server (para testes em memória)
# Run Tests with MongoDB Connection String
CONFIG_MONGO_URI=mongodb://localhost:27017 node mongodb-lens.test.js

# Run Tests with In-Memory MongoDB (requires mongodb-memory-server)
CONFIG_MONGO_URI=mongodb-memory-server node mongodb-lens.test.js

Para conveniência, os seguintes scripts estão disponíveis para executar os testes:

npm test                        # Fails if no CONFIG_MONGO_URI provided
npm run test:localhost          # Uses mongodb://localhost:27017
npm run test:localhost:verbose  # Runs with DEBUG=true for verbose output
npm run test:in-memory          # Uses mongodb-memory-server
npm run test:in-memory:verbose  # Runs with DEBUG=true for verbose output

[!NOTE]
A suíte de testes cria bancos de dados e coleções temporárias que são limpos após a conclusão dos testes.

Suíte de Testes: Opções de Linha de Comando

OpçãoDescrição
--listListar todos os testes disponíveis sem executá-los
--test=<n>Executar teste(s) específico(s) por nome (separados por vírgula)
--group=<n>Executar todos os testes em grupo(s) específico(s) (separados por vírgula)
--pattern=<glob>Executar testes que correspondem a padrão(ões) (separados por vírgula)

Suíte de Testes: Exemplos

# List All Available Tests
npm test -- --list

# Run Only Connection-Related Tests (:27017)
npm run test:localhost -- --group=Connection\ Tools

# Test Specific Database Operations (In-Memory)
npm run test:in-memory -- --test=create-database\ Tool,drop-database\ Tool

# Test All Document-Related Tools (:27017)
npm run test:localhost -- --pattern=document

# Run Resource Tests Only (In-Memory)
npm run test:in-memory -- --group=Resources

# Run Specific Tests Only (In-Memory)
npm run test:in-memory -- --test=aggregate-data\ Tool,find-documents\ Tool

Aviso Legal

O MongoDB Lens:

  • é licenciado sob a Licença MIT.
  • não é afiliado ou endossado pela MongoDB, Inc.
  • foi escrito com assistência de IA e pode conter erros.
  • destina-se apenas a fins educacionais e experimentais.
  • é fornecido como está, sem garantia — use por sua conta e risco.

Suporte

Se você achou o MongoDB Lens útil, considere apoiar meu trabalho através de:

Buy Me a Coffee | GitHub Sponsorship

As contribuições me ajudam a continuar desenvolvendo e melhorando esta ferramenta, permitindo que eu dedique mais tempo para adicionar novos recursos e garantir que ela continue sendo um recurso valioso para a comunidade.