MCP-сервер MongoDB

Версия НПМ Загрузки НПМ Лицензия НПМ значок кузнеца

Сервер Model Context Protocol, который позволяет LLM взаимодействовать с базами данных MongoDB. Этот сервер предоставляет возможности для проверки схем коллекций и выполнения операций MongoDB через стандартизированный интерфейс.

Демо

Демонстрация сервера MCP MongoDB | Рабочий стол Клода

Related MCP server: MongoDB MCP Server for LLMs

Основные характеристики

Интеллектуальная обработка ObjectId

Интеллектуальное преобразование между строковыми идентификаторами и MongoDB ObjectId
Настраивается с помощью параметра objectIdMode :
- "auto" : Преобразование на основе имен полей (по умолчанию)
- "none" : нет преобразования
- "force" : принудительно установить все поля идентификатора строки в ObjectId

Гибкая конфигурация

Переменные среды :
- MCP_MONGODB_URI : URI соединения MongoDB
- MCP_MONGODB_READONLY : включить режим «только чтение», если установлено значение «true»
Параметры командной строки :
- --read-only или -r : Подключиться в режиме только для чтения

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

Защита от операций записи (обновление, вставка, создание индекса)
Использует вторичный приоритет чтения MongoDB для оптимальной производительности
Идеально подходит для безопасного подключения к производственным базам данных

Операции MongoDB

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

Интеграция LLM

Завершения коллекции для улучшенного взаимодействия LLM
Вывод схемы для лучшего понимания контекста
Анализ сбора данных для понимания сути данных

Установка

Глобальная установка

npm install -g mcp-mongo-server

Для развития

# Clone repository
git clone https://github.com/kiliczsh/mcp-mongo-server.git
cd mcp-mongo-server

# Install dependencies
npm install

# Build
npm run build

# Development with auto-rebuild
npm run watch

Использование

Базовое использование

# Start server with MongoDB URI
npx -y mcp-mongo-server mongodb://muhammed:kilic@localhost:27017/database

# Connect in read-only mode
npx -y mcp-mongo-server mongodb://muhammed:kilic@localhost:27017/database --read-only

Переменные среды

Вы можете настроить сервер с помощью переменных среды, что особенно полезно для конвейеров CI/CD, контейнеров Docker или в тех случаях, когда вы не хотите раскрывать сведения о подключении в аргументах команды:

# Set MongoDB connection URI
export MCP_MONGODB_URI="mongodb://muhammed:kilic@localhost:27017/database"

# Enable read-only mode
export MCP_MONGODB_READONLY="true"

# Run server (will use environment variables if no URI is provided)
npx -y mcp-mongo-server

Использование переменных среды в конфигурации Claude Desktop:

{
  "mcpServers": {
    "mongodb-env": {
      "command": "npx",
      "args": [
        "-y",
        "mcp-mongo-server"
      ],
      "env": {
        "MCP_MONGODB_URI": "mongodb://muhammed:kilic@localhost:27017/database",
        "MCP_MONGODB_READONLY": "true"
      }
    }
  }
}

Использование переменных среды с Docker:

# Build
docker build -t mcp-mongo-server .

# Run
docker run -it -d -e MCP_MONGODB_URI="mongodb://muhammed:kilic@localhost:27017/database" -e MCP_MONGODB_READONLY="true" mcp-mongo-server

# or edit docker-compose.yml and run
docker-compose up -d

Интеграция с Claude Desktop

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

Добавьте конфигурацию сервера в файл конфигурации Claude Desktop:

MacOS : ~/Library/Application Support/Claude/claude_desktop_config.json Windows : %APPDATA%/Claude/claude_desktop_config.json

Подход с аргументами командной строки:

{
  "mcpServers": {
    "mongodb": {
      "command": "npx",
      "args": [
        "-y",
        "mcp-mongo-server",
        "mongodb://muhammed:kilic@localhost:27017/database"
      ]
    },
    "mongodb-readonly": {
      "command": "npx",
      "args": [
        "-y",
        "mcp-mongo-server",
        "mongodb://muhammed:kilic@localhost:27017/database",
        "--read-only"
      ]
    }
  }
}

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

{
  "mcpServers": {
    "mongodb": {
      "command": "npx",
      "args": [
        "-y",
        "mcp-mongo-server"
      ],
      "env": {
        "MCP_MONGODB_URI": "mongodb://muhammed:kilic@localhost:27017/database"
      }
    },
    "mongodb-readonly": {
      "command": "npx",
      "args": [
        "-y",
        "mcp-mongo-server"
      ],
      "env": {
        "MCP_MONGODB_URI": "mongodb://muhammed:kilic@localhost:27017/database",
        "MCP_MONGODB_READONLY": "true"
      }
    }
  }
}

Использование пакета GitHub:

{
  "mcpServers": {
    "mongodb": {
      "command": "npx",
      "args": [
        "-y",
        "github:kiliczsh/mcp-mongo-server",
        "mongodb://muhammed:kilic@localhost:27017/database"
      ]
    },
    "mongodb-readonly": {
      "command": "npx",
      "args": [
        "-y",
        "github:kiliczsh/mcp-mongo-server",
        "mongodb://muhammed:kilic@localhost:27017/database",
        "--read-only"
      ]
    }
  }
}

Интеграция с Windsurf и Cursor

Сервер MCP MongoDB можно использовать с Windsurf и Cursor аналогично Claude Desktop.

Конфигурация виндсерфинга

Добавьте сервер в конфигурацию Windsurf:

{
  "mcpServers": {
    "mongodb": {
      "command": "npx",
      "args": [
        "-y",
        "mcp-mongo-server",
        "mongodb://muhammed:kilic@localhost:27017/database"
      ]
    }
  }
}

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

Для курсора добавьте конфигурацию сервера в свои настройки:

{
  "mcpServers": {
    "mongodb": {
      "command": "npx",
      "args": [
        "-y",
        "mcp-mongo-server",
        "mongodb://muhammed:kilic@localhost:27017/database"
      ]
    }
  }
}

Вы также можете использовать подход с переменными среды как с Windsurf, так и с Cursor, следуя той же схеме, которая показана в конфигурации Claude Desktop.

Автоматическая установка

Использование кузнечного дела :

npx -y @smithery/cli install mcp-mongo-server --client claude

Использование mcp-get :

npx @michaellatman/mcp-get@latest install mcp-mongo-server

Доступные инструменты

Операции запроса

запрос : выполнение запросов MongoDB

{
  collection: "users",
  filter: { age: { $gt: 30 } },
  projection: { name: 1, email: 1 },
  limit: 20,
  explain: "executionStats"  // Optional
}

агрегат : запуск конвейеров агрегации

{
  collection: "orders",
  pipeline: [
    { $match: { status: "completed" } },
    { $group: { _id: "$customerId", total: { $sum: "$amount" } } }
  ],
  explain: "queryPlanner"  // Optional
}

count : Количество соответствующих документов
```
{
  collection: "products",
  query: { category: "electronics" }
}
```

Операции записи

обновление : Изменить документы

{
  collection: "posts",
  filter: { _id: "60d21b4667d0d8992e610c85" },
  update: { $set: { title: "Updated Title" } },
  upsert: false,
  multi: false
}

вставить : Добавить новые документы

{
  collection: "comments",
  documents: [
    { author: "user123", text: "Great post!" },
    { author: "user456", text: "Thanks for sharing" }
  ]
}

createIndex : Создание индексов коллекций

{
  collection: "users",
  indexes: [
    {
      key: { email: 1 },
      unique: true,
      name: "email_unique_idx"
    }
  ]
}

Системные операции

serverInfo : Получить сведения о сервере MongoDB
```
{
  includeDebugInfo: true  // Optional
}
```

Отладка

Поскольку серверы MCP взаимодействуют через stdio, отладка может быть сложной. Используйте MCP Inspector для лучшей видимости:

npm run inspector

Это предоставит URL-адрес для доступа к инструментам отладки в вашем браузере.

Запуск оценок

Пакет evals загружает клиент mcp, который затем запускает файл index.ts, поэтому нет необходимости перестраиваться между тестами. Вы можете загрузить переменные среды, указав префикс команды npx. Полную документацию можно найти здесь .

OPENAI_API_KEY=your-key  npx mcp-eval src/evals/evals.ts src/schemas/tools.ts

Лицензия

Этот сервер MCP лицензирован по лицензии MIT. Это означает, что вы можете свободно использовать, изменять и распространять программное обеспечение в соответствии с условиями лицензии MIT. Для получения более подробной информации см. файл LICENSE в репозитории проекта.

MongoDB