MongoDB MCP Server

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

📚 Содержание

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

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

  • Настройка

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

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

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

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

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

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

  • Доступ к Atlas API

  • Методы конфигурации

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

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

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

• 🤝 Вклад в проект

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

• Node.js (v20.10.0 или новее)

node -v

• Строка подключения MongoDB или учетные данные Atlas API, сервер не запустится без настройки.

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

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

Настройка

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

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

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

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

• Windsurf:https://docs.windsurf.com/windsurf/mcp

• VSCode: https://code.visualstudio.com/docs/copilot/chat/mcp-servers

• Claude Desktop: https://modelcontextprotocol.io/quickstart/user

• Cursor: https://docs.cursor.com/context/model-context-protocol

Вариант 1: Аргументы строки подключения

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

{
  "mcpServers": {
    "MongoDB": {
      "command": "npx",
      "args": [
        "-y",
        "mongodb-mcp-server",
        "--connectionString",
        "mongodb://localhost:27017/myDatabase"
      ]
    }
  }
}

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

Вариант 2: Аргументы учетных данных 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"
      ]
    }
  }
}

Вариант 3: Автономный сервис с использованием аргументов командной строки

Запустите сервер с помощью команды npx:

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

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

• Для настройки учетных данных сервисных учетных записей Atlas обратитесь к разделу Доступ к Atlas API

Вариант 4: Автономный сервис с использованием переменных окружения

 npx -y mongodb-mcp-server

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

• Строка подключения через переменные окружения в 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

docker run --rm -i \
  -e MDB_MCP_CONNECTION_STRING="mongodb+srv://username:password@cluster.mongodb.net/myDatabase" \
  mongodb/mongodb-mcp-server:latest

Вариант C: С учетными данными Atlas API

docker run --rm -i \
  -e MDB_MCP_API_CLIENT_ID="your-atlas-service-accounts-client-id" \
  -e MDB_MCP_API_CLIENT_SECRET="your-atlas-service-accounts-client-secret" \
  mongodb/mongodb-mcp-server:latest

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

Без параметров:

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

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

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

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

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

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

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

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

• atlas-list-orgs - Список организаций MongoDB Atlas

• atlas-list-projects - Список проектов MongoDB Atlas

• atlas-create-project - Создает новый проект MongoDB Atlas

• atlas-list-clusters - Список кластеров MongoDB Atlas

• atlas-inspect-cluster - Проверка конкретного кластера MongoDB Atlas

• atlas-create-free-cluster - Создание бесплатного кластера MongoDB Atlas

• atlas-connect-cluster - Подключение к кластеру MongoDB Atlas

• atlas-inspect-access-list - Проверка диапазонов IP/CIDR с доступом к кластерам MongoDB Atlas

• atlas-create-access-list - Настройка списка доступа IP/CIDR для кластеров MongoDB Atlas

• atlas-list-db-users - Список пользователей баз данных MongoDB Atlas

• atlas-create-db-user - Создание пользователя базы данных MongoDB Atlas

• atlas-list-alerts - Список оповещений MongoDB Atlas для проекта

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

Инструменты баз данных MongoDB

• connect - Подключение к экземпляру MongoDB

• find - Выполнение запроса find к коллекции MongoDB

• aggregate - Выполнение агрегации по коллекции MongoDB

• count - Получение количества документов в коллекции MongoDB

• insert-one - Вставка одного документа в коллекцию MongoDB

• insert-many - Вставка нескольких документов в коллекцию MongoDB

• create-index - Создание индекса для коллекции MongoDB

• update-one - Обновление одного документа в коллекции MongoDB

• update-many - Обновление нескольких документов в коллекции MongoDB

• rename-collection - Переименование коллекции MongoDB

• delete-one - Удаление одного документа из коллекции MongoDB

• delete-many - Удаление нескольких документов из коллекции MongoDB

• drop-collection - Удаление коллекции из базы данных MongoDB

• drop-database - Удаление базы данных MongoDB

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

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

• collection-indexes - Описание индексов для коллекции

• collection-schema - Описание схемы для коллекции

• collection-storage-size - Получение размера коллекции в МБ

• db-stats - Возврат статистики о базе данных MongoDB

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

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

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

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

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

Путь к журналу

Расположение журнала по умолчанию следующее:

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

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

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

Вы можете отключить конкретные инструменты или категории инструментов, используя опцию disabledTools. Эта опция принимает массив строк, где каждая строка может быть именем инструмента, типом операции или категорией.

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

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

• Для конфигурации через аргумент командной строки используйте строку, разделённую пробелами: --disabledTools create update delete atlas collectionSchema.

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

• atlas - Инструменты MongoDB Atlas, такие как list clusters, create cluster и т. д.

• mongodb - Инструменты базы данных MongoDB, такие как find, aggregate и т. д.

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

• create - Инструменты, создающие ресурсы, такие как create cluster, insert document и т. д.

• update - Инструменты, обновляющие ресурсы, такие как update document, rename collection и т. д.

• delete - Инструменты, удаляющие ресурсы, такие как delete document, drop collection и т. д.

• read - Инструменты, читающие ресурсы, такие как find, aggregate, list clusters и т. д.

• metadata - Инструменты, читающие метаданные, такие как list databases, list collections, collection schema и т. д.

Режим только для чтения

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

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

Вы можете включить режим только для чтения, используя:

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

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

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

Телеметрия

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

Вы можете отключить телеметрию, используя:

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

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

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

Доступ к Atlas API

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

ℹ️ Примечание: Подробную информацию о минимально необходимых разрешениях для каждой операции Atlas см. в разделе Разрешения Atlas API ниже.

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

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

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

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

   • Введите имя, описание и срок действия для вашего сервисного аккаунта (например, "MCP, MCP Server Access, 7 дней")

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

     • См. Разрешения Atlas API для подробностей.

   • Нажмите "Create"

Чтобы узнать больше о сервисных аккаунтах, ознакомьтесь с документацией MongoDB Atlas.

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

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

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

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

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

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

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

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

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

Краткий справочник: требуемые роли для каждой операции

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

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

Полный список ролей и их привилегий см. в документации по ролям пользователей Atlas.

Методы конфигурации

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

Установите переменные окружения с префиксом MDB_MCP_, за которым следует имя опции в верхнем регистре с подчёркиваниями:

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

export MDB_MCP_LOG_PATH="/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"
      }
    }
  }
}

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

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

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" --logPath=/path/to/logs

Примеры файлов конфигурации MCP

Строка подключения с аргументами командной строки

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

Учётные данные 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"
      ]
    }
  }
}

🤝 Вклад в проект

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