API VEGA

MongoDB MCP Server

MCP-сервер на базе Model Context Protocol для работы с базами данных MongoDB и MongoDB Atlas.

Быстрый старт

Использование официальных плагинов MongoDB для AI-агентов

В состав MongoDB MCP Server входят официальные плагины MongoDB для AI-агентов. Доступны следующие плагины:

mongodb-atlas — подключается к Atlas MCP-серверу, размещённому в инфраструктуре MongoDB, по протоколу OAuth. Ничего не нужно запускать локально — это рекомендуемый способ подключения к MongoDB Atlas из вашего AI-агента:

  • Cursor: маркетплейс

  • VSCode: откройте панель Extensions (⇧⌘X / Ctrl+Shift+X), выполните поиск по @agentPlugins и установите mongodb-atlas.

  • Claude: маркетплейс

  • Codex: откройте /plugins и установите mongodb-atlas.

  • GitHub Copilot CLI: выполните команду copilot plugin install mongodb-atlas.

  • Grok: откройте /marketplace в Grok Build и установите mongodb-atlas.

mongodb — запускает MongoDB MCP-сервер локально и подключается к любому самостоятельно управляемому развёртыванию:

  • Cursor: маркетплейс

  • Claude: маркетплейс

  • Gemini: маркетплейс

  • Codex: выполните команду codex plugin marketplace add mongodb/agent-skills, затем откройте /plugins и установите mongodb.

  • GitHub Copilot CLI: выполните команду copilot plugin install mongodb.

  • Grok: откройте /marketplace в Grok Build и установите mongodb.

Использование скрипта настройки

Локальный MCP-сервер можно настроить вручную, выполнив следующую команду:

npx -y mongodb-mcp-server@latest setup

Скрипт проведёт вас через интерактивный процесс настройки, включая конфигурацию строки подключения MongoDB или учётных данных Atlas API.

О расширенных вариантах настройки см. раздел Ручная настройка ниже.

Использование skill для настройки MongoDB MCP Server

С помощью AI-агента можно добавить skill настройки MongoDB MCP Server и использовать его для конфигурации локального MCP-сервера.

npx skills add https://github.com/mongodb/agent-skills --skill mongodb-mcp-setup
Ручная конфигурация

Инструкции по ручной настройке MongoDB MCP Server приведены в разделе Ручная настройка.

📚 Содержание

  • 🚀 Начало работы

    • Предварительные требования

    • Ручная настройка

  • 🛠️ Поддерживаемые инструменты

    • Инструменты MongoDB Atlas

    • Инструменты для работы с базами данных MongoDB

    • Инструменты MongoDB Assistant

  • 📄 Поддерживаемые ресурсы

  • ⚙️ Конфигурация

    • Параметры конфигурации

    • Доступ к Atlas API

    • Способы конфигурации

    • Переменные окружения

    • Аргументы командной строки

    • Конфигурация MCP-клиентов

    • Поддержка прокси

  • 🚀 Развёртывание в публичных облаках

    • Azure Cloud

  • 🤝 Участие в разработке

Предварительные требования

Примечание

Поддержка Node 20.x объявлена устаревшей и будет удалена в будущих релизах. Обновитесь до Node 22.13 или более поздней версии. Подробности миграции см. в https://nodejs.org/en/blog/migrations/v20-to-v22.

  • Node.js

    • Не ниже v22.13.0. Проверить версию можно командой node -v.

  • Строка подключения MongoDB или учётные данные Atlas API.

    • Для работы с инструментами Atlas необходимы учётные данные Service Accounts Atlas API. Создайте сервисный аккаунт в MongoDB Atlas и используйте его учётные данные для аутентификации. Подробнее см. в разделе Доступ к Atlas API.

    • Если у вас есть строка подключения MongoDB, используйте её напрямую для подключения к своему инстансу MongoDB.

Ручная настройка

🔒 Рекомендация по безопасности № 1: при работе с учётными данными Atlas API назначайте сервисному аккаунту только минимально необходимый набор разрешений. Подробнее см. в разделе Разрешения Atlas API.

🔒 Рекомендация по безопасности № 2: для дополнительной безопасности настоятельно рекомендуем передавать конфиденциальные данные — строки подключения и учётные данные API — через переменные окружения, а не через аргументы командной строки. Аргументы командной строки видны в списках процессов и могут сохраняться в различных системных логах, что создаёт риск раскрытия секретов. Переменные окружения обеспечивают более безопасный способ работы с чувствительной информацией.

Чтобы добавить MCP-сервер, в большинстве MCP-клиентов требуется создать или изменить файл конфигурации.

Примечание: синтаксис файла конфигурации может отличаться в разных клиентах. Актуальные требования к синтаксису смотрите по следующим ссылкам:

Предупреждение о безопасности по умолчанию: во всех примерах ниже по умолчанию указан флаг --readOnly, обеспечивающий безопасный доступ к данным только для чтения. Удалите --readOnly, если вам нужны операции записи.

Вариант 1: строка подключения

Строку подключения можно передать через переменные окружения — убедитесь, что используете корректные имя пользователя и пароль.

{
  "mcpServers": {
    "MongoDB": {
      "command": "npx",
      "args": ["-y", "mongodb-mcp-server@latest", "--readOnly"],
      "env": {
        "MDB_MCP_CONNECTION_STRING": "mongodb://localhost:27017/myDatabase"
      }
    }
  }
}

ПРИМЕЧАНИЕ: строку подключения можно настроить для любого кластера MongoDB — как локального инстанса, так и кластера Atlas.

Вариант 2: подключение к MCP-серверу под управлением MongoDB Atlas

При работе с MongoDB Atlas рекомендуемый подход — установить плагин mongodb-atlas для вашего AI-агента: он автоматически выполняет аутентификацию через OAuth.

Инструкции по ручной настройке Atlas Remote MCP-сервера с OAuth для конкретного клиента см. в инструкциях для клиентов. Альтернативный вариант — подключение через пакет mongodb-atlas-mcp-remote с учётными данными Service Account; порядок настройки описан в README пакета.

Примечание: аутентификация на удалённом MongoDB MCP-сервере по HTTP со статическим API-ключом невозможна. Доступны два варианта:

  • Использовать клиент с поддержкой OAuth.

  • Использовать stdio-сервер mongodb-atlas-mcp-remote, аутентификация в котором выполняется через статические переменные окружения MDB_MCP_API_CLIENT_ID и MDB_MCP_API_CLIENT_SECRET.

Чтобы подключиться к stdio-серверу mongodb-atlas-mcp-remote с учётными данными Service Account, добавьте его в конфигурацию MCP вашего клиента:

{
  "mcpServers": {
    "mongodb-atlas-mcp-remote": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "mongodb-atlas-mcp-remote@latest"],
      "env": {
        "MDB_MCP_API_CLIENT_ID": "$CLIENT_ID",
        "MDB_MCP_API_CLIENT_SECRET": "$SECRET"
      }
    }
  }
}
Вариант 3: учётные данные Atlas API

Используйте учётные данные Service Accounts для Atlas API. Предварительно необходимо выполнить все шаги из раздела Доступ к Atlas API.

{
  "mcpServers": {
    "MongoDB": {
      "command": "npx",
      "args": ["-y", "mongodb-mcp-server@latest", "--readOnly"],
      "env": {
        "MDB_MCP_API_CLIENT_ID": "your-atlas-service-accounts-client-id",
        "MDB_MCP_API_CLIENT_SECRET": "your-atlas-service-accounts-client-secret"
      }
    }
  }
}
Вариант 4: автономный сервис с переменными окружения и аргументами командной строки

Можно подгрузить переменные окружения из файла конфигурации или задать их явно, как в примере ниже, а затем запустить сервер через npx.

# Set your credentials as environment variables first
export MDB_MCP_API_CLIENT_ID="your-atlas-service-accounts-client-id"
export MDB_MCP_API_CLIENT_SECRET="your-atlas-service-accounts-client-secret"

# Then start the server
npx -y mongodb-mcp-server@latest --readOnly

💡 Примечание о платформах: в примерах выше используется синтаксис Unix/Linux/macOS. Пользователям Windows следует обратиться к разделу Переменные окружения за инструкциями для своей платформы.

  • Полный список параметров конфигурации см. в разделе Параметры конфигурации

  • Настройка учётных данных Atlas Service Accounts описана в разделе Доступ к Atlas API

  • Пример строки подключения через переменные окружения в MCP-файле

  • Пример учётных данных Atlas API через переменные окружения в MCP-файле

Вариант 5: использование Docker

MongoDB MCP Server можно запустить в Docker-контейнере: это обеспечивает изоляцию и не требует локальной установки Node.js.

Запуск с переменными окружения

Можно передать либо строку подключения MongoDB, либо учётные данные Atlas API:

Вариант A: без конфигурации
docker run --rm -i \
  mongodb/mongodb-mcp-server:latest
Вариант B: со строкой подключения MongoDB
# Set your credentials as environment variables first
export MDB_MCP_CONNECTION_STRING="mongodb+srv://username:password@cluster.mongodb.net/myDatabase"

# Then start the docker container
docker run --rm -i \
  -e MDB_MCP_CONNECTION_STRING \
  -e MDB_MCP_READ_ONLY="true" \
  mongodb/mongodb-mcp-server:latest

💡 Примечание о платформах: в примерах выше используется синтаксис Unix/Linux/macOS. Пользователям Windows следует обратиться к разделу «Переменные окружения», где приведены инструкции для конкретных платформ.

Вариант C: с учётными данными Atlas API
# Set your credentials as environment variables first
export MDB_MCP_API_CLIENT_ID="your-atlas-service-accounts-client-id"
export MDB_MCP_API_CLIENT_SECRET="your-atlas-service-accounts-client-secret"

# Then start the docker container
docker run --rm -i \
  -e MDB_MCP_API_CLIENT_ID \
  -e MDB_MCP_API_CLIENT_SECRET \
  -e MDB_MCP_READ_ONLY="true" \
  mongodb/mongodb-mcp-server:latest

💡 Примечание о платформах: в примерах выше используется синтаксис Unix/Linux/macOS. Пользователям Windows следует обратиться к разделу «Переменные окружения», где приведены инструкции для конкретных платформ.

Docker в файле конфигурации MCP

Без дополнительных параметров:

{
  "mcpServers": {
    "MongoDB": {
      "command": "docker",
      "args": [
        "run",
        "--rm",
        "-e",
        "MDB_MCP_READ_ONLY=true",
        "-i",
        "mongodb/mongodb-mcp-server:latest"
      ]
    }
  }
}

Со строкой подключения:

{
  "mcpServers": {
    "MongoDB": {
      "command": "docker",
      "args": [
        "run",
        "--rm",
        "-i",
        "-e",
        "MDB_MCP_CONNECTION_STRING",
        "-e",
        "MDB_MCP_READ_ONLY=true",
        "mongodb/mongodb-mcp-server:latest"
      ],
      "env": {
        "MDB_MCP_CONNECTION_STRING": "mongodb+srv://username:password@cluster.mongodb.net/myDatabase"
      }
    }
  }
}

С учётными данными Atlas API:

{
  "mcpServers": {
    "MongoDB": {
      "command": "docker",
      "args": [
        "run",
        "--rm",
        "-i",
        "-e",
        "MDB_MCP_READ_ONLY=true",
        "-e",
        "MDB_MCP_API_CLIENT_ID",
        "-e",
        "MDB_MCP_API_CLIENT_SECRET",
        "mongodb/mongodb-mcp-server:latest"
      ],
      "env": {
        "MDB_MCP_API_CLIENT_ID": "your-atlas-service-accounts-client-id",
        "MDB_MCP_API_CLIENT_SECRET": "your-atlas-service-accounts-client-secret"
      }
    }
  }
}

🛠️ Поддерживаемые инструменты

Список инструментов

Инструменты для работы с базами данных MongoDB

  • aggregate — запускает агрегацию для коллекции MongoDB

  • aggregate-db — запускает агрегацию для базы данных MongoDB

  • collection-indexes — описывает индексы коллекции

  • collection-schema — описывает схему коллекции

  • collection-storage-size — возвращает размер коллекции

  • connect — подключается к экземпляру MongoDB

  • count — возвращает количество документов в коллекции MongoDB с помощью db.collection.count(), где query выступает необязательным параметром фильтрации

  • create-collection — создаёт новую коллекцию в базе данных. Если база данных не существует, она будет создана автоматически.

  • create-index — создаёт индекс для коллекции

  • db-stats — возвращает статистику, отражающую состояние использования отдельной базы данных

  • delete-many — удаляет все документы, соответствующие фильтру, из коллекции MongoDB

  • disconnect — закрывает соединение с MongoDB и отзывает его connectionId.

  • drop-collection — удаляет коллекцию или представление из базы данных. Метод также удаляет все индексы, связанные с удалённой коллекцией.

  • drop-database — удаляет указанную базу данных вместе с связанными файлами данных

  • drop-index — удаляет индекс для указанных базы данных и коллекции.

  • explain — возвращает статистику, описывающую выполнение оптимального плана, выбранного оптимизатором запросов для оцениваемого метода

  • export — экспортирует результаты запроса или агрегации в указанном формате EJSON.

  • find — выполняет запрос find к коллекции MongoDB

  • insert-many — вставляет массив документов в коллекцию MongoDB. Если размер списка документов превышает com.mongodb/maxRequestPayloadBytes, рекомендуется вставлять их пакетами.

  • list-collections — выводит список всех коллекций указанной базы данных

  • list-connections — выводит список активных соединений MongoDB и их connectionId. Используйте этот инструмент, чтобы найти connectionId, установленный ранее.

  • list-databases — выводит список всех баз данных для соединения MongoDB

  • mongodb-logs — возвращает последние события из журнала mongod

  • rename-collection — переименовывает коллекцию в базе данных MongoDB

  • update-many — обновляет все документы коллекции, соответствующие указанному фильтру. Если размер списка документов превышает com.mongodb/maxRequestPayloadBytes, рекомендуется обновлять их пакетами.

Инструменты MongoDB Atlas
  • atlas-connect-cluster — подключается к кластеру MongoDB Atlas и возвращает connectionId, который затем передаётся другим инструментам MongoDB. Каждый вызов создаёт новое независимое подключение — одновременно могут быть активны несколько подключений.
  • atlas-create-access-list — разрешает диапазонам IP/CIDR доступ к вашим кластерам MongoDB Atlas.
  • atlas-create-cluster — создаёт кластер MongoDB Atlas (M10–M80, replica set или single shard). Автомасштабирование вычислений включено по умолчанию: минимальный размер инстанса устанавливается равным выбранному размеру инстанса, максимальный — на два уровня выше. Автомасштабирование диска всегда включено. Поддерживается шифрование при хранении с использованием ключей, управляемых клиентом (CMK); у провайдера CMK уже должна быть действующая конфигурация шифрования при хранении в проекте. Инструмент возвращает управление сразу; используйте инструмент atlas-inspect-cluster, чтобы опрашивать состояние кластера до готовности (состояние: IDLE). Строки подключения недоступны, пока кластер не достигнет состояния IDLE.
  • atlas-create-db-user — создаёт пользователя базы данных MongoDB Atlas.
  • atlas-create-free-cluster — создаёт бесплатный кластер MongoDB Atlas.
  • atlas-create-project — создаёт проект MongoDB Atlas.
  • atlas-get-performance-advisor — возвращает рекомендации и предложения Performance Advisor для MongoDB Atlas, включая операции: рекомендуемые индексы, предложения по удалению индексов, предложения по схеме и выборку последних (не более 50) логов медленных запросов.
  • atlas-get-regions — выводит список поддерживаемых регионов MongoDB Atlas для облачного провайдера.
  • atlas-inspect-access-list — показывает диапазоны IP/CIDR, имеющие доступ к вашим кластерам MongoDB Atlas.
  • atlas-inspect-cluster — показывает метаданные кластера MongoDB Atlas.
  • atlas-list-alerts — выводит список сработавших оповещений для проекта MongoDB Atlas. Это оповещения, которые сгенерировал Atlas, а не конфигурации оповещений, которые их определяют. По умолчанию показывает оповещения со статусом OPEN; задайте статус TRACKING или CLOSED, чтобы увидеть остальные.
  • atlas-list-clusters — выводит список кластеров MongoDB Atlas.
  • atlas-list-db-users — выводит список пользователей баз данных MongoDB Atlas.
  • atlas-list-orgs — выводит список организаций MongoDB Atlas.
  • atlas-list-projects — выводит список проектов MongoDB Atlas.
  • atlas-load-sample-dataset — загружает демонстрационный набор данных MongoDB в кластер Atlas или проверяет статус ранее запущенной загрузки. Чтобы запустить новую загрузку, укажите clusterName — загрузка выполняется асинхронно, а ответ содержит jobId и начальное состояние. Чтобы проверить прогресс, вызовите этот инструмент снова с jobId (загрузка демонстрационных наборов данных обычно занимает 1–5 минут). Состояние может быть WORKING, COMPLETED или FAILED.
  • atlas-pause-resume-cluster — приостанавливает или возобновляет выделенный кластер MongoDB Atlas (M10+).
  • atlas-streams-build — создаёт ресурсы Atlas Stream Processing. Используйте этот инструмент для задач «настроить конвейер Kafka», «создать рабочее пространство», «добавить подключение» или «развернуть процессор». Используйте resource='workspace', чтобы создать новое рабочее пространство (укажите облачного провайдера, регион и уровень). Используйте resource='connection', чтобы добавить источник или приёмник данных в существующее рабочее пространство. Используйте resource='processor', чтобы развернуть потоковый процессор с конвейером. Используйте resource='privatelink', чтобы настроить приватную сеть. Типичный сценарий: создать рабочее пространство → добавить подключения → развернуть процессор.
  • atlas-streams-discover — находит и просматривает ресурсы Atlas Stream Processing. Также используйте для запросов «почему мой процессор завершается с ошибкой», «какие рабочие пространства у меня есть», «показать статистику процессора» или «проверить состояние процессора». Используйте 'list-workspaces', чтобы увидеть все рабочие пространства в проекте. Используйте действия inspect для получения подробностей о конкретном ресурсе. Используйте 'diagnose-processor' для сводного отчёта о работоспособности, включающего состояние, статистику, состояние подключений и последние ошибки. Используйте 'get-networking' для PrivateLink и сведений об учётной записи.
  • atlas-streams-manage — управляет ресурсами Atlas Stream Processing: запускает/останавливает процессоры, изменяет конвейеры, обновляет конфигурации. Также используйте для запросов «изменить конвейер», «увеличить масштаб моего процессора» или «обновить уровень моего рабочего пространства». Типичный сценарий: action='stop-processor' → action='modify-processor' → action='start-processor'. Перед управлением используйте atlas-streams-discover с действием 'inspect-processor', чтобы проверить состояние.
  • atlas-streams-teardown — удаляет ресурсы Atlas Stream Processing. Также используйте для запросов «удалить моё рабочее пространство», «отключить источник», «удалить все процессоры» или «очистить мою среду streams». Перед удалением выполняет базовые проверки безопасности: суммирует количество процессоров и подключений, по возможности выделяет подключения, на которые ссылаются процессоры, и выводит ошибки API, если при попытке удаления процессоры всё ещё работают. Перед удалением используйте atlas-streams-discover, чтобы просмотреть ресурсы.
  • atlas-upgrade-cluster — обновляет или масштабирует кластер MongoDB Atlas. Кластеры Free и Flex можно обновить до Flex или M10 Dedicated. Выделенные кластеры можно масштабировать до другого размера инстанса, а настройки автомасштабирования вычислений можно обновить. При масштабировании выделенного кластера необходимо указать хотя бы один из параметров targetTier, computeAutoScaling, minInstanceSize или maxInstanceSize. При обновлении до M10 Dedicated автомасштабирование вычислений по умолчанию включено: минимальный размер инстанса устанавливается равным выбранному размеру инстанса, максимальный — на два уровня выше, если не переопределено. Примечание для LLM: если провайдер и регион ещё не известны, запросите оба вместе одним вопросом перед вызовом этого инструмента. Перед вызовом этого инструмента используйте atlas-get-regions, чтобы сопоставить местоположения, заданные естественным языком, или неоднозначные коды регионов.

ПРИМЕЧАНИЕ: инструменты atlas доступны только при указании учётных данных в разделе конфигурации.

Инструменты MongoDB Atlas Local
  • atlas-local-connect-deployment — подключается к развёртыванию MongoDB Atlas Local и возвращает connectionId, который затем передаётся другим инструментам MongoDB.
  • atlas-local-create-deployment — создаёт локальное развёртывание MongoDB Atlas. По умолчанию используется образ preview. Если пользователь не указал тег образа, сообщите ему, что по умолчанию используется preview, и предоставьте эту ссылку для получения дополнительной информации: https://hub.docker.com/r/mongodb/mongodb-atlas-local
  • atlas-local-delete-deployment — удаляет локальное развёртывание MongoDB Atlas.
  • atlas-local-list-deployments — выводит список локальных развёртываний MongoDB Atlas.
Инструменты MongoDB Assistant
  • list-knowledge-sources — выводит список доступных источников данных в базе знаний MongoDB Assistant. Используйте это, чтобы изучить доступные источники данных или найти параметры фильтрации поиска для использования в search-knowledge.
  • search-knowledge — ищет информацию в базе знаний MongoDB Assistant. Она включает официальную документацию, проверенные экспертные рекомендации и другие ресурсы, предоставленные MongoDB. Поддерживает фильтрацию по источнику данных и версии.

📄 Поддерживаемые ресурсы

  • config — конфигурация сервера, задаваемая пользователем через переменные среды или аргументы запуска, при этом чувствительные параметры скрываются. Доступ к ресурсу можно получить по URI config://config.
  • debug — отладочная информация для проблем с подключением к MongoDB. Отслеживает последнюю попытку подключения и сведения об ошибке. Доступ к ресурсу можно получить по URI debug://mongodb.
  • exported-data — шаблон ресурса для доступа к данным, экспортированным с помощью инструмента export. Доступ к шаблону можно получить по URI exported-data://{exportName}, где exportName — уникальное имя экспорта, созданного инструментом export.

Конфигурация

🔒 Рекомендации по безопасности: Мы настоятельно рекомендуем использовать переменные среды для конфиденциальной конфигурации, такой как учётные данные API (MDB_MCP_API_CLIENT_ID, MDB_MCP_API_CLIENT_SECRET) и строки подключения (MDB_MCP_CONNECTION_STRING), вместо аргументов командной строки. Переменные среды не видны в списках процессов и обеспечивают лучшую защиту конфиденциальных данных.

MongoDB MCP Server можно настроить несколькими способами; приоритет следующий (от высшего к низшему):

  • Аргументы командной строки
  • Переменные среды
  • Файл конфигурации

Параметры конфигурации

Переменная окружения / опция CLIПо умолчаниюОписание
MDB_MCP_AGGREGATION_COUNT_MAX_TIME_MS_CAP / --aggregationCountMaxTimeMsCap60000Максимальное время в миллисекундах для фазы подсчёта (count) операций агрегации. Используется для ограничения времени, затрачиваемого на подсчёт документов при определении того, был ли результат усечён.
MDB_MCP_ALLOW_REQUEST_OVERRIDES / --allowRequestOverridesfalseЕсли установлено значение true, разрешает переопределение значений конфигурации через заголовки запросов и query-параметры.
MDB_MCP_API_CLIENT_ID / --apiClientId``Client ID для Atlas API, используемый для аутентификации. Требуется для работы инструментов Atlas.
MDB_MCP_API_CLIENT_SECRET / --apiClientSecret``Client secret для Atlas API, используемый для аутентификации. Требуется для работы инструментов Atlas.
MDB_MCP_ASSISTANT_BASE_URL / --assistantBaseUrl"https://knowledge.mongodb.com/api/v1/"Базовый URL для MongoDB Assistant API.
MDB_MCP_ATLAS_TEMPORARY_DATABASE_USER_LIFETIME_MS / --atlasTemporaryDatabaseUserLifetimeMs14400000Время в миллисекундах, в течение которого временные пользователи базы данных, создаваемые при подключении к кластерам MongoDB Atlas, остаются активными, после чего автоматически удаляются.
MDB_MCP_CONFIRMATION_REQUIRED_TOOLS / --confirmationRequiredTools"atlas-create-access-list,atlas-create-db-user,drop-database,drop-collection,delete-many,drop-index,atlas-streams-manage,atlas-streams-teardown"Список названий инструментов (через запятую), требующих подтверждения пользователя перед выполнением. Требует от клиента поддержки elicitation.
MDB_MCP_CONNECTION_IDLE_TIMEOUT_MS / --connectionIdleTimeoutMs600000Время в миллисекундах, в течение которого соединение MongoDB может оставаться неиспользуемым (без обращений через вызовы инструментов), прежде чем оно будет закрыто для освобождения пула соединений и его состояния на стороне сервера. Применяется к каждому соединению независимо от его scope; преднастроенное соединение исключено, а фоновый процесс очистки (reaper) запускается с этим интервалом. Установите 0, чтобы отключить очистку; отрицательные значения не допускаются.
MDB_MCP_CONNECTION_SCOPE / --connectionScope"session"Область видимости (scope) соединений MongoDB, создаваемых во время выполнения. В режиме 'session' (по умолчанию) каждая сессия MCP видит только созданные ею соединения (плюс общее соединение 'preconfigured'), и они закрываются по завершении сессии. В режиме 'global' соединения общие для всех сессий и сохраняются при ротации сессий. Устарело: протокол MCP движется к бессессионной модели, поэтому эта опция скоро будет удалена, а scope соединений по умолчанию станет 'global'. Для сценариев с общим сервером используйте Atlas-Managed MCP server или создайте аутентифицированную библиотеку с помощью пакета @mongodb-js/mcp-cli. Примечание: на бессессионном (2026-07-28) HTTP-пути запрос без mcp-session-id откатывается к общему ('global') scope, благодаря чему соединения всё ещё могут сохраняться между запросами; на устаревшем сессионном пути сессия, выданная сервером, присутствует всегда.
MDB_MCP_CONNECTION_STRING / --connectionString``Строка подключения MongoDB для прямого подключения к базе данных. Необязательно: если не задана, перед работой с данными MongoDB потребуется вызвать инструмент connect.
MDB_MCP_DANGEROUS_HOST_BINDING / --dangerousHostBindingfalseЕсли установлено значение true, разрешает привязку HTTP-сервера (и сервера мониторинга) к хосту, отличному от loopback, например 0.0.0.0, IP-адресу локальной сети или пустому хосту (все интерфейсы). Привязка к хосту, отличному от loopback, открывает доступ к серверу всей сети и может привести к несанкционированному доступу. По умолчанию отключено: сервер откажется запускаться на хосте, отличном от loopback, если эта опция не включена.
MDB_MCP_DISABLE_SERVER_SIDE_JS / --disableServerSideJstrueЕсли установлено значение true, запрещает использование операторов серверного JavaScript (таких как $where, $function и $accumulator) в фильтрах запросов и конвейерах агрегации.
MDB_MCP_DISABLED_TOOLS / --disabledTools""Список названий инструментов, типов операций и/или категорий инструментов (через запятую), которые будут отключены.
MDB_MCP_DRY_RUN / --dryRunfalseЕсли true, сервер работает в режиме dry run: выводит конфигурацию и список включённых инструментов, после чего завершает работу без запуска сервера.
MDB_MCP_ELICITATION_TIMEOUT_MS / --elicitationTimeoutMs300000Время в миллисекундах, отведённое пользователю на ответ на elicitation-запрос (например, запрос подтверждения инструмента), по истечении которого запрос завершается ошибкой.
MDB_MCP_EVICTION_IDLE_GRACE_M_S / --evictionIdleGraceMS120000Время, в течение которого сессия должна простаивать, прежде чем она станет кандидатом на вытеснение по принципу LRU (least-recently-used) при достижении HTTP-транспортом лимита maxSessions (используется только при транспорте 'http'). Если значение больше idleTimeoutMs, оно приводится к idleTimeoutMs.
MDB_MCP_EXPORT_CLEANUP_INTERVAL_MS / --exportCleanupIntervalMs120000Интервал в миллисекундах между циклами очистки экспорта, в ходе которых удаляются просроченные файлы экспорта.
MDB_MCP_EXPORT_TIMEOUT_MS / --exportTimeoutMs300000Время в миллисекундах, по истечении которого экспорт считается просроченным и подлежит очистке.
MDB_MCP_EXPORTS_PATH / --exportsPathсм. ниже*Папка для хранения экспортированных файлов данных.
MDB_MCP_EXTERNALLY_MANAGED_SESSIONS / --externallyManagedSessionsfalseЕсли true, HTTP-транспорт образца 2025 года принимает идентификатор сессии, переданный извне через заголовок 'mcp-session-id'. При наличии внешнего ID запрос инициализации необязателен, а неявно реинициализированная сессия восстанавливает ранее согласованные клиентом возможности из хранилища сессий.
MDB_MCP_HEALTH_CHECK_HOST / --healthCheckHost``Устарело. Используйте вместо него monitoringServerHost. Адрес хоста для привязки healthCheck HTTP-сервера (используется только при транспорте 'http'). Если указано, необходимо также задать healthCheckPort.
MDB_MCP_HEALTH_CHECK_PORT / --healthCheckPort``Устарело. Используйте вместо него monitoringServerPort. Номер порта healthCheck HTTP-сервера (используется только при транспорте 'http'). Если указано, необходимо также задать healthCheckHost.
MDB_MCP_HTTP_BODY_LIMIT / --httpBodyLimit102400Максимальный размер тела HTTP-запроса в байтах (используется только при транспорте 'http'). Значение передаётся как необязательный параметр limit в middleware json() фреймворка Express.js.
MDB_MCP_HTTP_HEADERS / --httpHeaders"{}"Заголовок, который HTTP-сервер проверяет при обработке запросов (используется только при транспорте 'http').
MDB_MCP_HTTP_HOST / --httpHost"127.0.0.1"Адрес хоста, к которому привязывается HTTP-сервер (используется только при транспорте 'http').
MDB_MCP_HTTP_PORT / --httpPort3000Номер порта HTTP-сервера (используется только при транспорте 'http'). Используйте 0 для случайного порта.
MDB_MCP_HTTP_RESPONSE_TYPE / --httpResponseType"sse"Тип HTTP-ответа для результатов инструментов: 'sse' для Server-Sent Events, 'json' для стандартных JSON-ответов.
MDB_MCP_IDLE_TIMEOUT_MS / --idleTimeoutMs600000Время бездействия, по истечении которого клиент отключается (применяется только к http-транспорту).
MDB_MCP_INDEX_CHECK / --indexCheckfalseЕсли установлено значение true, требует, чтобы операции запросов использовали индекс, и отклоняет запросы, выполняющие сканирование коллекции (collection scan).
MDB_MCP_LOG_PATH / --logPathсм. ниже*Папка для хранения логов.
MDB_MCP_LOGGERS / --loggers"disk,mcp" см. ниже*Список типов логгеров (через запятую).
MDB_MCP_MAX_ACTIVE_CONNECTIONS / --maxActiveConnections10Максимальное количество соединений MongoDB, которое один scope (по умолчанию — сессия MCP, см. connectionScope) может держать открытыми. При превышении лимита наименее недавно использовавшееся соединение scope закрывается, а его connectionId отзывается. Преднастроенное соединение не учитывается в лимите.
MDB_MCP_MAX_BYTES_PER_QUERY / --maxBytesPerQuery16777216Максимальный размер в байтах результатов вызова инструментов find или aggregate. Служит верхней границей для параметра responseBytesLimit в этих инструментах.
MDB_MCP_MAX_DOCUMENTS_PER_QUERY / --maxDocumentsPerQuery100Максимальное количество документов, которое может вернуть вызов инструментов find или aggregate. Для инструмента find фактический лимит равен меньшему из этого значения и параметра limit инструмента.
MDB_MCP_MAX_SESSIONS / --maxSessions1000Максимальное количество одновременных сессий, которое HTTP-транспорт хранит в памяти (используется только при транспорте 'http'). Каждая сессия содержит полноценный экземпляр сервера, транспорт и таймеры, поэтому выбирайте значение с учётом доступной памяти вашего развёртывания; значение по умолчанию — консервативная мера предосторожности, а не рекомендуемое значение для production.
MDB_MCP_MAX_TIME_M_S / --maxTimeMS``Максимальное время в миллисекундах, в течение которого операциям разрешено выполняться на сервере MongoDB. Если задано, значение передаётся как опция maxTimeMS в операции чтения, такие как find, aggregate и count.
MDB_MCP_MCP_CLIENT_LOG_LEVEL / --mcpClientLogLevel"debug"Минимальный уровень критичности лог-сообщений, пересылаемых клиенту MCP.

| MDB_MCP_MONITORING_SERVER_FEATURES / --monitoringServerFeatures | "health-check" | Функции, предоставляемые сервером мониторинга (используется только при транспорте 'http' и заданных monitoringServerHost/monitoringServerPort). | | MDB_MCP_MONITORING_SERVER_HOST / --monitoringServerHost | | Адрес хоста, к которому привязывается HTTP-сервер мониторинга (используется только при транспорте 'http'). Если указан, необходимо также задать `monitoringServerPort`. | | `MDB_MCP_MONITORING_SERVER_PORT` / `--monitoringServerPort` | | Порт HTTP-сервера мониторинга (используется только при транспорте 'http'). Если указан, необходимо также задать monitoringServerHost. | | MDB_MCP_NOTIFICATION_TIMEOUT_MS / --notificationTimeoutMs | 540000 | Таймаут уведомления, позволяющий клиенту узнать об отключении (применяется только к транспорту http). | | MDB_MCP_PREVIEW_FEATURES / --previewFeatures | "" | Разделённый запятыми список включённых preview-функций. | | MDB_MCP_QUERY_COUNT_MAX_TIME_MS_CAP / --queryCountMaxTimeMsCap | 10000 | Максимальное время в миллисекундах для фазы подсчёта в операциях find. Ограничивает время, затрачиваемое на подсчёт документов при определении того, было ли количество результатов усечено лимитом. | | MDB_MCP_READ_ONLY / --readOnly | false | Если установлено значение true, разрешены только операции чтения, подключения и работы с метаданными, а операции создания, обновления и удаления отключаются. | | MDB_MCP_TELEMETRY / --telemetry | "enabled" | Если установлено значение disabled, сбор телеметрии отключается. | | MDB_MCP_TRANSPORT / --transport | "stdio" | Допустимые значения: 'stdio' или 'http'. | | MDB_MCP_VOYAGE_API_KEY / --voyageApiKey | "" | API-ключ для сервиса эмбеддингов Voyage AI (требуется для создания развёртываний Atlas Local с поддержкой векторного поиска auto-embed). |

Параметры логирования

Параметр конфигурации loggers определяет, куда отправляются журналы. Можно указать один или несколько типов логгеров в виде списка, разделённого запятыми. Доступные варианты:

  • mcp: отправляет журналы MCP-клиенту (если клиент/транспорт это поддерживает).

  • disk: записывает журналы в файлы на диске. Файлы журналов сохраняются по пути, заданному параметром logPath (см. выше).

  • stderr: выводит журналы в стандартный поток ошибок (stderr) — удобно при отладке или запуске в контейнерах.

По умолчанию: disk,mcp (журналы записываются на диск и отправляются MCP-клиенту).

Можно комбинировать несколько логгеров, например --loggers disk stderr или export MDB_MCP_LOGGERS="mcp,stderr".

Пример: настройка логгера через переменную окружения
export MDB_MCP_LOGGERS="disk,stderr"

💡 Примечание о платформах: пользователям Windows следует обратиться к разделу «Переменные окружения» за инструкциями, специфичными для этой платформы.

Пример: настройка логгера через аргумент командной строки
npx -y mongodb-mcp-server@latest --loggers mcp stderr
Расположение файлов журналов

При использовании логгера disk файлы журналов сохраняются в:

  • Windows: %LOCALAPPDATA%\mongodb\mongodb-mcp\.app-logs

  • macOS/Linux: ~/.mongodb/mongodb-mcp/.app-logs

Каталог журналов можно переопределить параметром logPath.

🔒 Рекомендация по безопасности: учётная запись, от имени которой запускается MCP-сервер, должна иметь права и на чтение, и на запись для каталога logPath. Убедитесь, что этот каталог надёжно защищён соответствующими правами доступа файловой системы, чтобы исключить несанкционированный доступ к файлам журналов.

Отключение инструментов

С помощью параметра disabledTools можно отключать отдельные инструменты или целые их категории. Этот параметр принимает массив строк,

где каждая строка — имя инструмента, тип операции или категория.

Способ задания массива зависит от выбранного метода конфигурации:

  • При настройке через переменную окружения используйте строку с разделителем-запятой: export MDB_MCP_DISABLED_TOOLS="create,update,delete,atlas,collectionSchema".

  • При настройке через аргумент командной строки используйте строку с разделителем-пробелом: --disabledTools create update delete atlas collectionSchema.

Категории инструментов:

  • atlas — инструменты MongoDB Atlas, например список кластеров, создание кластера и т. д.

  • mongodb — инструменты для работы с базами данных MongoDB, например find, aggregate и т. д.

Типы операций:

  • create — инструменты, создающие ресурсы: создание кластера, вставка документа и т. д.

  • update — инструменты, обновляющие ресурсы: обновление документа, переименование коллекции и т. д.

  • delete — инструменты, удаляющие ресурсы: удаление документа, удаление коллекции и т. д.

  • read — инструменты, читающие ресурсы: find, aggregate, список кластеров и т. д.

  • metadata — инструменты, читающие метаданные: список баз данных/коллекций/индексов, определение схемы коллекции и т. д.

  • connect — инструменты, позволяющие подключаться к экземпляру MongoDB или переключать соединение. Если эта категория отключена, строку подключения потребуется передать через конфигурацию при запуске сервера.

Запрос подтверждения

Если ваш клиент поддерживает elicitation, можно настроить MongoDB MCP-сервер так, чтобы он запрашивал подтверждение пользователя перед выполнением определённых инструментов.

Когда инструмент помечен как требующий подтверждения, сервер отправляет клиенту elicitation-запрос. Клиент с поддержкой elicitation покажет пользователю запрос на подтверждение и вернёт ответ серверу. Если клиент не поддерживает elicitation, инструмент выполнится без подтверждения.

Параметр конфигурации confirmationRequiredTools позволяет указать имена инструментов, требующих подтверждения. По умолчанию эта настройка включена для следующих инструментов: drop-database, drop-collection, delete-many, drop-index, atlas-create-db-user, atlas-create-access-list, atlas-streams-manage, atlas-streams-teardown.

Кроме того, инструменты aggregate и aggregate-db всегда запрашивают подтверждение перед выполнением конвейера, содержащего стадию $out или $merge, независимо от того, перечислены ли они в confirmationRequiredTools. Эти стадии выполняют запись в коллекцию — $out полностью заменяет её содержимое, — поэтому в запросе подтверждения указываются затрагиваемая коллекция и то, что с ней произойдёт. Конвейеры без стадии записи выполняются без подтверждения.

Добавление любого из этих инструментов в confirmationRequiredTools действует шире: в этом случае каждое обращение подтверждается заранее стандартным сообщением уровня инструмента, а стадия записи повторного запроса уже не вызывает.

Режим «только чтение»

Параметр конфигурации readOnly ограничивает MCP-сервер использованием только инструментов с типами операций «read», «connect» и «metadata». При включении этого режима все инструменты с типами операций «create», «update» или «delete» не будут зарегистрированы на сервере.

Это полезно в сценариях, когда нужно предоставить доступ к данным MongoDB для анализа, не допуская изменения данных или инфраструктуры.

Включить режим «только чтение» можно так:

  • Переменная окружения: export MDB_MCP_READ_ONLY=true

  • Аргумент командной строки: --readOnly

💡 Примечание о платформах: пользователям Windows следует обратиться к разделу «Переменные окружения» за инструкциями, специфичными для этой платформы.

Когда режим «только чтение» активен, в журналах сервера появится сообщение с указанием инструментов, регистрация которых была заблокирована этим ограничением.

Режим проверки индексов

Параметр конфигурации indexCheck позволяет требовать, чтобы операции запросов использовали индекс. При включении этого режима запросы, выполняющие полное сканирование коллекции, будут отклоняться — это помогает обеспечить более высокую производительность.

Это полезно, когда нужно гарантировать, что запросы к базе данных оптимизированы.

Включить режим проверки индексов можно так:

  • Переменная окружения: export MDB_MCP_INDEX_CHECK=true

  • Аргумент командной строки: --indexCheck

💡 Примечание о платформах: пользователям Windows следует обратиться к разделу «Переменные окружения» за инструкциями, специфичными для этой платформы.

Когда режим проверки индексов активен, при отклонении запроса из-за отсутствия индекса будет выведено сообщение об ошибке.

Экспорт данных

Данные, экспортированные инструментом export, временно хранятся по настроенному пути exportsPath на машине, где запущен MCP-сервер, пока не будут удалены в рамках процесса очистки экспорта. Если параметр exportsPath не задан, используются следующие значения по умолчанию:

  • Windows: %LOCALAPPDATA%\mongodb\mongodb-mcp\exports

  • macOS/Linux: ~/.mongodb/mongodb-mcp/exports

Параметр exportTimeoutMs задаёт время, по истечении которого экспортированные данные считаются устаревшими и подлежат очистке. По умолчанию срок действия экспорта истекает через 5 минут (300000 мс).

Параметр exportCleanupIntervalMs определяет частоту запуска процесса очистки, удаляющего устаревшие файлы экспорта. По умолчанию очистка выполняется каждые 2 минуты (120000 мс).

🔒 Рекомендация по безопасности: учётная запись, от имени которой запускается MCP-сервер, должна иметь права и на чтение, и на запись для каталога exportsPath. Убедитесь, что этот каталог надёжно защищён соответствующими правами доступа файловой системы, чтобы исключить несанкционированный доступ к файлам экспорта — они могут содержать конфиденциальные данные MongoDB. Выбирая место для экспорта, учитывайте чувствительность своих данных и назначайте соответствующие ограничительные права доступа.

Телеметрия

Параметр конфигурации telemetry позволяет отключить сбор телеметрии. Если телеметрия включена, MCP-сервер собирает данные об использовании и отправляет их в MongoDB.

Отключить телеметрию можно так:

  • Переменная окружения: export MDB_MCP_TELEMETRY=disabled

  • Аргумент командной строки: --telemetry disabled

  • Переменная окружения DO_NOT_TRACK: export DO_NOT_TRACK=1

💡 Примечание о платформах: пользователям Windows следует обратиться к разделу «Переменные окружения» за инструкциями, специфичными для этой платформы.

Включение предварительных функций

MongoDB MCP Server может предоставлять функциональность, которая ещё находится в разработке и может измениться в будущих релизах. Такие возможности считаются «предварительными» (preview features) и по умолчанию отключены. Как правило, они хорошо протестированы, но могут не обладать всей функциональностью, которую планируется предоставить в финальном релизе, либо мы хотим сначала собрать отзывы, прежде чем делать их общедоступными. Чтобы включить одну или несколько предварительных функций, используйте параметр конфигурации previewFeatures.

  • При настройке через переменную окружения используйте строку с разделителем-запятой: export MDB_MCP_PREVIEW_FEATURES="feature1,feature2".

  • При настройке через аргумент командной строки используйте строку с разделителем-пробелом: --previewFeatures feature1 feature2.

Список доступных предварительных функций:

  • mcpUI — включает опциональный веб-интерфейс для взаимодействия с MCP-сервером.
Сервер мониторинга (проверки состояния и метрики)

При запуске с --transport http можно поднять отдельный HTTP-сервер мониторинга для проверок состояния и метрик. Такой сервер запускается только если заданы одновременно monitoringServerHost и monitoringServerPort, и слушает на собственном хосте и порту (независимо от основных httpHost/httpPort).

Состав доступных функций задаётся параметром monitoringServerFeatures (по умолчанию: health-check). Доступные функции и их эндпоинты:

ФункцияЭндпоинтОписание
health-check/healthВозвращает 200 OK с JSON-телом, описывающим состояние сервера. Полезно для liveness-проб.
metrics/metricsВозвращает метрики сервера в текстовом формате Prometheus.

Ответ /health отправляется с заголовком Cache-Control: no-store и имеет следующую структуру (status всегда равен "ok", пока процесс жив):

{
  "status": "ok",
  "version": "1.13.0",
  "uptimeSeconds": 42,
  "timestamp": "2026-06-20T12:00:00.000Z"
}

Пример: запустите сервер с включённым мониторингом и вызовите эндпоинт health-check:

npx -y mongodb-mcp-server@latest --transport http --httpHost 0.0.0.0 --httpPort 3000 --monitoringServerHost 0.0.0.0 --monitoringServerPort 8080 &
curl http://0.0.0.0:8080/health
# => {"status":"ok","version":"1.13.0","uptimeSeconds":42,"timestamp":"2026-06-20T12:00:00.000Z"}

Чтобы открыть оба эндпоинта, явно перечислите функции:

npx -y mongodb-mcp-server@latest --transport http --monitoringServerHost 0.0.0.0 --monitoringServerPort 8080 --monitoringServerFeatures health-check,metrics

💡 Примечание: healthCheckHost / healthCheckPort — устаревшие псевдонимы для monitoringServerHost / monitoringServerPort; они по-прежнему открывают тот же эндпоинт /health.

Доступ к Atlas API

Для работы с инструментами Atlas API потребуется создать сервисный аккаунт в MongoDB Atlas:

ℹ️ Примечание: подробный разбор минимально необходимых прав для каждой операции Atlas приведён ниже, в разделе «Разрешения Atlas API».

  • Создайте сервисный аккаунт:

    • Войдите в MongoDB Atlas на cloud.mongodb.com

    • Перейдите в Access Manager > Organization Access

    • Нажмите Add New > Applications > Service Accounts

    • Укажите имя, описание и срок действия сервисного аккаунта (например, «MCP, MCP Server Access, 7 days»)

    • Назначайте только минимально необходимые для вашего сценария права.

    • Подробнее — в разделе «Разрешения Atlas API».

    • Нажмите «Create»

Подробнее о сервисных аккаунтах можно узнать в документации MongoDB Atlas.

  • Сохраните учётные данные клиента:

    • Сразу после создания вам будут показаны Client ID и Client Secret

    • Важно: немедленно скопируйте и сохраните Client Secret — повторно он показан не будет

  • Добавьте запись в список доступа:

    • Добавьте свой IP-адрес в список доступа к API

  • Настройте MCP-сервер:

    • Используйте один из способов конфигурации, описанных ниже, чтобы задать apiClientId и apiClientSecret

Разрешения Atlas API

Предупреждение о безопасности: роль Organization Owner требуется крайне редко и может представлять риск для безопасности. Назначайте только минимально необходимые для вашего сценария права.

Краткая справка: необходимые роли для каждой операции
ЗадачаСамая безопасная роль для назначения (уровень)
Просмотр списка организаций/проектовOrg Member или Org Read Only (Org)
Создание новых проектовOrg Project Creator (Org)
Просмотр кластеров/баз данных в проектеProject Read Only (Project)
Создание кластеров в проекте и управление имиProject Cluster Manager (Project)
Управление списками доступа проектаProject IP Access List Admin (Project)
Управление пользователями баз данныхProject Database Access Admin (Project)
Управление ресурсами Stream ProcessingProject Stream Processing Owner (Project)

  • Для большинства операций предпочитайте роли уровня проекта. Назначайте их только тем конкретным проектам, которые нужно администрировать или просматривать.

  • Избегайте роли Organization Owner, если только вам не нужен полный административный контроль над всеми проектами и настройками организации.

Полный список ролей и их привилегий приведён в документации Atlas User Roles.

Способы конфигурации

Файл конфигурации

Храните конфигурацию в JSON-файле и загружайте её с помощью переменной окружения MDB_MCP_CONFIG.

🔒 Лучшая практика безопасности: для чувствительных полей предпочтительнее переменная окружения MDB_MCP_CONFIG, а не файл конфигурации или аргумент командной строки --config — аргументы командной строки видны в списке процессов.

🔒 Безопасность файла: убедитесь, что файл конфигурации имеет корректные владельца и права доступа, ограниченные пользователем, от имени которого запущен MongoDB MCP-сервер: Linux/macOS:

chmod 600 /path/to/config.json
chown your-username /path/to/config.json

Windows: щёлкните по файлу правой кнопкой мыши → Свойства → Безопасность → ограничьте доступ только своей учётной записью.

Создайте JSON-файл с конфигурацией (все ключи в camelCase):

{
  "connectionString": "mongodb://localhost:27017",
  "readOnly": true,
  "loggers": ["stderr", "mcp"],
  "apiClientId": "your-atlas-service-accounts-client-id",
  "apiClientSecret": "your-atlas-service-accounts-client-secret",
  "maxDocumentsPerQuery": 100
}

Linux/macOS (bash/zsh):

export MDB_MCP_CONFIG="/path/to/config.json"
npx -y mongodb-mcp-server@latest

Windows Command Prompt (cmd):

set "MDB_MCP_CONFIG=C:\path\to\config.json"
npx -y mongodb-mcp-server@latest

Windows PowerShell:

$env:MDB_MCP_CONFIG="C:\path\to\config.json"
npx -y mongodb-mcp-server@latest
Переменные окружения

Задайте переменные окружения с префиксом MDB_MCP_, за которым следует имя параметра прописными буквами с символами подчёркивания:

Linux/macOS (bash/zsh):

# 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 log path
export MDB_MCP_LOG_PATH="/path/to/logs"

Windows Command Prompt (cmd):

set "MDB_MCP_API_CLIENT_ID=your-atlas-service-accounts-client-id"
set "MDB_MCP_API_CLIENT_SECRET=your-atlas-service-accounts-client-secret"

set "MDB_MCP_CONNECTION_STRING=mongodb+srv://username:password@cluster.mongodb.net/myDatabase"

set "MDB_MCP_LOG_PATH=C:\path\to\logs"

Windows PowerShell:

# Set Atlas API credentials (via Service Accounts)
$env:MDB_MCP_API_CLIENT_ID="your-atlas-service-accounts-client-id"
$env:MDB_MCP_API_CLIENT_SECRET="your-atlas-service-accounts-client-secret"

# Set a custom MongoDB connection string
$env:MDB_MCP_CONNECTION_STRING="mongodb+srv://username:password@cluster.mongodb.net/myDatabase"

# Set log path
$env:MDB_MCP_LOG_PATH="C:\path\to\logs"
Примеры файлов конфигурации MCP
Строка подключения через переменные окружения
{
  "mcpServers": {
    "MongoDB": {
      "command": "npx",
      "args": ["-y", "mongodb-mcp-server"],
      "env": {
        "MDB_MCP_CONNECTION_STRING": "mongodb+srv://username:password@cluster.mongodb.net/myDatabase"
      }
    }
  }
}
Учётные данные Atlas API через переменные окружения
{
  "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"
      }
    }
  }
}
Аргументы командной строки

Передавайте параметры конфигурации в виде аргументов командной строки при запуске сервера:

🔒 Замечание по безопасности: для чувствительных данных — учётных данных API и строк подключения — используйте переменные окружения вместо аргументов командной строки.

# Set sensitive data as environment variable
export MDB_MCP_API_CLIENT_ID="your-atlas-service-accounts-client-id"
export MDB_MCP_API_CLIENT_SECRET="your-atlas-service-accounts-client-secret"
export MDB_MCP_CONNECTION_STRING="mongodb+srv://username:password@cluster.mongodb.net/myDatabase"

# Start the server with command line arguments
npx -y mongodb-mcp-server@latest --logPath=/path/to/logs --readOnly --indexCheck

💡 Замечание о платформе: в примерах выше используется синтаксис Unix/Linux/macOS. Пользователям Windows следует обратиться к разделу «Переменные окружения» за инструкциями для своей платформы.

Примеры файлов конфигурации MCP
Строка подключения через аргументы командной строки

🔒 Примечание о безопасности: Не рекомендуем передавать строку подключения в качестве аргумента командной строки. Строка подключения может содержать учётные данные, которые видны в списках процессов и могут попадать в журналы в разных местах системы, что потенциально приводит к их раскрытию. Вместо этого настройте строку подключения через переменные окружения

{
  "mcpServers": {
    "MongoDB": {
      "command": "npx",
      "args": [
        "-y",
        "mongodb-mcp-server",
        "mongodb+srv://username:password@cluster.mongodb.net/myDatabase",
        "--readOnly"
      ]
    }
  }
}
Учётные данные Atlas API через аргументы командной строки

🔒 Примечание о безопасности: Не рекомендуем передавать учётные данные Atlas API в качестве аргументов командной строки. Такие учётные данные видны в списках процессов и могут попадать в журналы в разных местах системы, что потенциально приводит к их раскрытию. Вместо этого настройте учётные данные Atlas API через переменные окружения

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

Поддержка прокси

MCP Server определяет стандартные переменные окружения прокси и использует их для поддерживаемых исходящих соединений, включая Atlas Administration API, подключения к кластерам MongoDB, провайдеров идентификации OIDC и MongoDB Assistant. Поведение совпадает с mongosh (оба опираются на @mongodb-js/devtools-proxy-support), поэтому любая конфигурация прокси, работающая с mongosh, будет работать и здесь.

Переменные окружения

Задайте нужную переменную перед запуском сервера. Поддерживаются стандартные переменные *_PROXY:

ПеременнаяНазначение
HTTPS_PROXYПрокси для HTTPS-запросов (Atlas API, OIDC, Assistant)
HTTP_PROXYПрокси для обычных HTTP-запросов
ALL_PROXYРезервный прокси для всех протоколов
NO_PROXYРазделённый запятыми список хостов/доменов, обращение к которым выполняется в обход прокси
# Route outbound traffic through a corporate proxy, except internal hosts
export HTTPS_PROXY="http://proxy.example.com:8080"
export NO_PROXY="localhost,127.0.0.1,*.internal.example.com"
Прокси в строке подключения

Для подключения к кластеру MongoDB можно настроить SOCKS5-прокси прямо в строке подключения, не прибегая к переменным окружения:

mongodb+srv://<host>/?proxyHost=127.0.0.1&proxyPort=1080&proxyUsername=user&proxyPassword=pass

Поддерживаемые параметры: proxyHost, proxyPort, proxyUsername, proxyPassword.

Центры сертификации

Для HTTP(S)-запросов, обрабатываемых @mongodb-js/devtools-proxy-support (Atlas API, OIDC и MongoDB Assistant), помимо встроенных CA доверяется хранилище сертификатов операционной системы — так же, как в mongosh, — поэтому корпоративные корневые сертификаты, установленные на уровне ОС, подхватываются автоматически.

🚀 Развёртывание в публичных облаках

Вы можете развернуть MongoDB MCP Server у предпочитаемого облачного провайдера, используя ресурсы для развёртывания из каталога deploy/. Каждое руководство описывает предварительные требования, конфигурацию и скрипты автоматизации, упрощающие развёртывание.

Azure

Подробные инструкции по Azure см. в deploy/azure/README.md.

Ограничения развёртывания

CLI-инструмент (mongodb-mcp-server / npx mongodb-mcp-server) предназначен для однопользовательских развёртываний на localhost (или в приватной сети), где единственным субъектом доступа выступает пользователь, от имени которого запущен сервер. Он поставляется без встроенной аутентификации, а протокол MCP не передаёт верифицированную идентичность конечного пользователя. Он не предназначен для обслуживания нескольких пользователей — перед ним нет промежуточного слоя аутентификации, который различал бы вызывающих сторон или управлял изоляцией подключений.

Поэтому, если вы открываете его в сеть — или запускаете как общий сервер, — ответственность за гарантии изоляции ложится на вас:

  • Доступ из интернета: привязка к 0.0.0.0 / :: (или любому хосту, отличному от loopback) без аутентификации открывает неаутентифицированную конечную точку, через которую можно выполнять операции MongoDB (включая деструктивные) с настроенной строкой подключения. Если вы намеренно привязываете сервер к хосту, отличному от loopback, необходимо задать MDB_MCP_DANGEROUS_HOST_BINDING=true (см. раздел «Параметры конфигурации»).

  • Изоляция между пользователями: подключения разделяются по областям видимости с помощью опции connectionScope (скоро будет удалена), значение которой по умолчанию меняется на global — все запросы используют одну общую область. Заголовок mcp-session-id, определяющий область на пути без сессий, задаётся на стороне клиента и не является границей безопасности; запросы без него попадают в общую область. В результате несколько пользователей могут видеть подключения друг друга и работать с ними, включая учётные данные временных пользователей баз данных Atlas. Сервер не различает вызывающих сторон. Чтобы обеспечить корректную изоляцию, вы можете либо настроить промежуточный слой с аутентификацией, контролирующий заголовок mcp-session-id, либо реализовать собственный механизм разделения областей с помощью библиотечных пакетов @mongodb-js/mcp-*.

Не запускайте CLI-инструмент как общедоступную в интернете конечную точку, не добавив перед ним собственный слой аутентификации и идентификации.

Используйте библиотеку и добавьте собственную аутентификацию

Для многопользовательских (multi-tenant) или публичных развёртываний вместо этого постройте решение с аутентификацией на основе библиотечных пакетов @mongodb-js/mcp-*:

  • Выполняйте аутентификацию / проверку идентичности пользователя на собственном прокси или промежуточном слое и передавайте верифицированного субъекта (principal) в запрос через authInfo (и createMcpHandler из SDK, и устаревший обработчик передают его дальше).

  • Задайте политику connectionScope, привязанную к верифицированной идентичности конечного пользователя (например, к claim sub в OIDC), чтобы подключения и учётные данные каждого пользователя были изолированы, — не позволяйте трафику нескольких пользователей попадать в общую область global.

Уже работаете с MongoDB Atlas? Для многопользовательской работы с кластерами Atlas самое простое решение — MongoDB Atlas-Managed MCP server: хостинговое развёртывание с аутентификацией, которое берёт на себя идентификацию каждого пользователя (OAuth / service-account), избавляя вас от необходимости создавать собственное. См. вариант 2 выше.

Сведения об API для встраивания, createHttpTransportRunnerFromConfig / CliMcpHttpServer, точке расширения политики connectionScope, а также готовый пример разделения областей по пользователям см. в MCP_SERVER_LIBRARY.md.

🤝 Участие в разработке

Хотите внести вклад в проект? Отлично! Ознакомьтесь с нашим руководством для контрибьюторов, где описаны правила внесения изменений в код, стандарты разработки, порядок добавления новых инструментов и информация по устранению неполадок.