MongoDB MCP Server

Um servidor para interagir com bancos de dados MongoDB e MongoDB Atlas.

GitHubExperimente este MCPPatrocinado

Documentação

MongoDB MCP Server

Um servidor Model Context Protocol para interagir com bancos de dados MongoDB e MongoDB Atlas.

📚 Sumário

Pré-requisitos

  • Node.js (v20 ou posterior)
node -v
  • Uma string de conexão do MongoDB ou credenciais da API Atlas, o Servidor não iniciará a menos que seja configurado.
    • Credenciais da API Atlas de Service Accounts são necessárias para usar as ferramentas Atlas. Você pode criar uma service account no MongoDB Atlas e usar suas credenciais para autenticação. Consulte Acesso à API Atlas para mais detalhes.
    • Se você tiver uma string de conexão do MongoDB, pode usá-la diretamente para conectar à sua instância do MongoDB.

Configuração

Início Rápido

A maioria dos clientes MCP exige que um arquivo de configuração seja criado ou modificado para adicionar o servidor MCP.

Nota: A sintaxe do arquivo de configuração pode variar entre clientes. Consulte os seguintes links para a sintaxe esperada mais recente:

🐳 Implantação com Docker

Oferecemos imagens Docker pré-construídas que podem ser baixadas via GitHub Actions:

Baixando a imagem:

  1. Acesse a página GitHub Actions
  2. Selecione o registro de build mais recente
  3. Baixe mongodb-mcp-server-{version}-amd64.tar.gz na seção "Artifacts"

Como usar:

# 解压并加载镜像
gunzip mongodb-mcp-server-{version}-amd64.tar.gz
docker load -i mongodb-mcp-server-{version}-amd64.tar

# 运行容器
docker run -d -p 8000:8000 \
  -e MDB_MCP_CONNECTION_STRING="mongodb+srv://username:password@cluster.mongodb.net/myDatabase" \
  -e MDB_DB="myDatabase" \
  mongodb-mcp-server:latest

# 或使用Atlas API凭据
docker run -d -p 8000:8000 \
  -e MDB_MCP_API_CLIENT_ID="your-client-id" \
  -e MDB_MCP_API_CLIENT_SECRET="your-client-secret" \
  mongodb-mcp-server:latest

Variáveis de ambiente do Docker:

  • PORT: Porta do serviço (padrão: 8000)
  • MDB_MCP_CONNECTION_STRING: String de conexão do MongoDB
  • MDB_DB: Nome padrão do banco de dados (padrão: ChatBI)
  • MDB_MCP_API_CLIENT_ID: ID do cliente da API Atlas
  • MDB_MCP_API_CLIENT_SECRET: Chave secreta do cliente da API Atlas

Opção 1: Argumentos de string de conexão

Você pode passar sua string de conexão via argumentos, certifique-se de usar um nome de usuário e senha válidos.

{
  "mcpServers": {
    "MongoDB": {
      "command": "npx",
      "args": [
        "-y",
        "mongodb-mcp-server",
        "--connectionString",
        "mongodb+srv://username:password@cluster.mongodb.net/myDatabase"
      ]
    }
  }
}

Opção 2: Argumentos de credenciais da API Atlas

Use as credenciais da sua Service Account da API Atlas. Deve seguir todos os passos na seção Acesso à API Atlas.

{
  "mcpServers": {
    "MongoDB": {
      "command": "npx",
      "args": [
        "-y",
        "mongodb-mcp-server",
        "--apiClientId",
        "your-atlas-service-accounts-client-id",
        "--apiClientSecret",
        "your-atlas-service-accounts-client-secret"
      ]
    }
  }
}

Opção 3: Serviço autônomo usando argumentos de linha de comando

Inicie o servidor usando o comando npx:

 npx -y mongodb-mcp-server --apiClientId="your-atlas-service-accounts-client-id" --apiClientSecret="your-atlas-service-accounts-client-secret"

Opção 4: Serviço autônomo usando variáveis de ambiente

 npx -y mongodb-mcp-server

Você pode usar variáveis de ambiente no arquivo de configuração ou defini-las e executar o servidor via npx.

  • String de conexão via variáveis de ambiente no arquivo MCP exemplo
  • Credenciais da API Atlas via variáveis de ambiente no arquivo MCP exemplo

🛠️ Ferramentas Suportadas

Lista de Ferramentas

Ferramentas do MongoDB Atlas

  • atlas-list-orgs - Lista organizações do MongoDB Atlas
  • atlas-list-projects - Lista projetos do MongoDB Atlas
  • atlas-create-project - Cria um novo projeto do MongoDB Atlas
  • atlas-list-clusters - Lista clusters do MongoDB Atlas
  • atlas-inspect-cluster - Inspeciona um cluster específico do MongoDB Atlas
  • atlas-create-free-cluster - Cria um cluster gratuito do MongoDB Atlas
  • atlas-connect-cluster - Conecta a um cluster do MongoDB Atlas
  • atlas-inspect-access-list - Inspeciona faixas de IP/CIDR com acesso a clusters do MongoDB Atlas
  • atlas-create-access-list - Configura a lista de acesso IP/CIDR para clusters do MongoDB Atlas
  • atlas-list-db-users - Lista usuários de banco de dados do MongoDB Atlas
  • atlas-create-db-user - Lista usuários de banco de dados do MongoDB Atlas

NOTA: as ferramentas Atlas só estão disponíveis quando você define credenciais na seção configuração.

Ferramentas do MongoDB Database

  • connect - Conecta a uma instância do MongoDB
  • find - Executa uma consulta find em uma coleção do MongoDB
  • aggregate - Executa uma agregação em uma coleção do MongoDB
  • count - Obtém o número de documentos em uma coleção do MongoDB
  • insert-one - Insere um único documento em uma coleção do MongoDB
  • insert-many - Insere vários documentos em uma coleção do MongoDB
  • create-index - Cria um índice para uma coleção do MongoDB
  • update-one - Atualiza um único documento em uma coleção do MongoDB
  • update-many - Atualiza vários documentos em uma coleção do MongoDB
  • rename-collection - Renomeia uma coleção do MongoDB
  • delete-one - Exclui um único documento de uma coleção do MongoDB
  • delete-many - Exclui vários documentos de uma coleção do MongoDB
  • drop-collection - Remove uma coleção de um banco de dados do MongoDB
  • drop-database - Remove um banco de dados do MongoDB
  • list-databases - Lista todos os bancos de dados para uma conexão do MongoDB
  • list-collections - Lista todas as coleções para um determinado banco de dados
  • collection-indexes - Descreve os índices de uma coleção
  • collection-schema - Descreve o esquema de uma coleção
  • collection-storage-size - Obtém o tamanho de uma coleção em MB
  • db-stats - Retorna estatísticas sobre um banco de dados do MongoDB

Configuração

O MongoDB MCP Server pode ser configurado usando vários métodos, com a seguinte precedência (da maior para a menor):

  1. Argumentos de linha de comando
  2. Variáveis de ambiente

Opções de Configuração

OpçãoDescrição
apiClientIdID do cliente da API Atlas para autenticação
apiClientSecretChave secreta do cliente da API Atlas para autenticação
connectionStringString de conexão do MongoDB para conexões diretas com o banco de dados (opcional; os usuários podem optar por informá-la em cada chamada de ferramenta)
defaultDatabaseNome padrão do banco de dados para operações do MongoDB. Pode ser definido via argumento --database ou variáveis de ambiente MDB_DB/MDB_MCP_DEFAULT_DATABASE. O padrão é "ChatBI"
logPathPasta para armazenar logs
disabledToolsUma matriz de nomes de ferramentas, tipos de operação e/ou categorias de ferramentas que serão desabilitadas
readOnlyQuando definido como true, permite apenas tipos de operação de leitura e metadados, desabilitando operações de criação/atualização/exclusão
telemetryQuando definido como disabled, desabilita a coleta de telemetria

Caminho do Log

O local padrão do log é o seguinte:

  • Windows: %LOCALAPPDATA%\mongodb\mongodb-mcp\.app-logs
  • macOS/Linux: ~/.mongodb/mongodb-mcp/.app-logs

Ferramentas Desabilitadas

Você pode desabilitar ferramentas específicas ou categorias de ferramentas usando a opção disabledTools. Esta opção aceita uma matriz de strings, onde cada string pode ser um nome de ferramenta, tipo de operação ou categoria.

A forma como a matriz é construída depende do tipo de método de configuração que você usa:

  • Para configuração por variável de ambiente, use uma string separada por vírgulas: export MDB_MCP_DISABLED_TOOLS="create,update,delete,atlas,collectionSchema".
  • Para configuração por argumento de linha de comando, use uma string separada por espaços: --disabledTools create update delete atlas collectionSchema.

Categorias de ferramentas:

  • atlas - Ferramentas do MongoDB Atlas, como listar clusters, criar cluster, etc.
  • mongodb - Ferramentas de banco de dados do MongoDB, como find, aggregate, etc.

Tipos de operação:

  • create - Ferramentas que criam recursos, como criar cluster, inserir documento, etc.
  • update - Ferramentas que atualizam recursos, como atualizar documento, renomear coleção, etc.
  • delete - Ferramentas que excluem recursos, como excluir documento, remover coleção, etc.
  • read - Ferramentas que leem recursos, como find, aggregate, listar clusters, etc.
  • metadata - Ferramentas que leem metadados, como listar bancos de dados, listar coleções, esquema de coleção, etc.

Modo Somente Leitura

A opção de configuração readOnly permite restringir o servidor MCP a usar apenas ferramentas com tipos de operação "read" e "metadata". Quando habilitada, todas as ferramentas que possuem tipos de operação "create", "update" ou "delete" não serão registradas no servidor.

Isso é útil para cenários em que você deseja fornecer acesso aos dados do MongoDB para análise sem permitir modificações nos dados ou na infraestrutura.

Você pode habilitar o modo somente leitura usando:

  • Variável de ambiente: export MDB_MCP_READ_ONLY=true
  • Argumento de linha de comando: --readOnly

Quando o modo somente leitura está ativo, você verá uma mensagem nos logs do servidor indicando quais ferramentas foram impedidas de serem registradas devido a essa restrição.

Restrição de Banco de Dados

A opção de configuração defaultDatabase permite restringir o servidor MCP a operar apenas em um banco de dados específico. Quando configurada, todas as ferramentas de banco de dados usarão o banco de dados especificado por padrão, e a ferramenta list-databases é desabilitada para evitar a descoberta de outros bancos de dados.

Isso é útil para cenários em que você deseja limitar o acesso a um banco de dados específico por motivos de segurança ou operacionais.

Você pode definir o banco de dados padrão usando:

  • Variável de ambiente: export MDB_DB=ChatBI ou export MDB_MCP_DEFAULT_DATABASE=ChatBI
  • Argumento de linha de comando: --database ChatBI
  • Variável de ambiente do Docker: -e MDB_DB=ChatBI

Quando um banco de dados padrão é configurado:

  • Todas as operações de banco de dados usarão este banco, a menos que seja explicitamente substituído nos argumentos da ferramenta
  • A ferramenta list-databases é desabilitada para evitar a descoberta de bancos de dados
  • Os usuários ainda podem especificar um nome de banco de dados diferente em chamadas individuais de ferramentas, se necessário

Telemetria

A opção de configuração telemetry permite desabilitar a coleta de telemetria. Quando habilitada, o servidor MCP coletará dados de uso e os enviará ao MongoDB.

Você pode desabilitar a telemetria usando:

  • Variável de ambiente: export MDB_MCP_TELEMETRY=disabled
  • Argumento de linha de comando: --telemetry disabled
  • Variável de ambiente DO_NOT_TRACK: export DO_NOT_TRACK=1

Acesso à API Atlas

Para usar as ferramentas da API Atlas, você precisará criar uma service account no MongoDB Atlas:

  1. Crie uma Service Account:

    • Faça login no MongoDB Atlas em cloud.mongodb.com
    • Navegue até Access Manager > Organization Access
    • Clique em Add New > Applications > Service Accounts
    • Insira nome, descrição e expiração para sua service account (por exemplo, "MCP, MCP Server Access, 7 days")
    • Selecione as permissões apropriadas (para acesso total, use Organization Owner)
    • Clique em "Create"

Para saber mais sobre Service Accounts, consulte a documentação do MongoDB Atlas.

  1. Salve as Credenciais do Cliente:

    • Após a criação, você verá o Client ID e o Client Secret
    • Importante: Copie e salve o Client Secret imediatamente, pois ele não será exibido novamente

  2. Adicione uma Entrada na Lista de Acesso:

    • Adicione seu endereço IP à lista de acesso da API

  3. Configure o Servidor MCP:

    • Use um dos métodos de configuração abaixo para definir seu apiClientId e apiClientSecret

Métodos de Configuração

Variáveis de Ambiente

Defina variáveis de ambiente com o prefixo MDB_MCP_ seguido pelo nome da opção em maiúsculas com sublinhados:

# 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"

# Set default database for operations (limits MCP to only use this database)
export MDB_MCP_DEFAULT_DATABASE="ChatBI"
# Or alternatively, use the shorter form:
export MDB_DB="ChatBI"

export MDB_MCP_LOG_PATH="/path/to/logs"

Exemplos de arquivo de configuração MCP

String de conexão com variáveis de ambiente
{
  "mcpServers": {
    "MongoDB": {
      "command": "npx",
      "args": ["-y", "mongodb-mcp-server"],
      "env": {
        "MDB_MCP_CONNECTION_STRING": "mongodb+srv://username:password@cluster.mongodb.net/myDatabase"
      }
    }
  }
}
Credenciais da API Atlas com variáveis de ambiente
{
  "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 Linha de Comando

Passe opções de configuração como argumentos de linha de comando ao iniciar o 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" --database="ChatBI" --logPath=/path/to/logs

Exemplos de arquivo de configuração MCP

String de conexão com argumentos de linha de comando
{
  "mcpServers": {
    "MongoDB": {
      "command": "npx",
      "args": [
        "-y",
        "mongodb-mcp-server",
        "--connectionString",
        "mongodb+srv://username:password@cluster.mongodb.net/myDatabase"
      ]
    }
  }
}
Credenciais da API Atlas com argumentos de linha de comando
{
  "mcpServers": {
    "MongoDB": {
      "command": "npx",
      "args": [
        "-y",
        "mongodb-mcp-server",
        "--apiClientId",
        "your-atlas-service-accounts-client-id",
        "--apiClientSecret",
        "your-atlas-service-accounts-client-secret"
      ]
    }
  }
}

🤝 Contribuindo

Interessado em contribuir? Ótimo! Por favor, consulte nosso Guia de Contribuição para diretrizes sobre contribuições de código, padrões, adição de novas ferramentas e informações de solução de problemas.