MotherDuck

Локальный MCP-сервер DuckDB / MotherDuck

SQL-аналитика и инжиниринг данных для AI-ассистентов и IDE.

Подключайте AI-ассистентов к вашим данным с помощью мощного аналитического SQL-движка DuckDB. Поддерживает подключение к локальным файлам DuckDB, базам данных в памяти, базам данных на S3 и MotherDuck. Позволяет выполнять SQL-запросы на чтение и запись, просматривать каталоги баз данных и переключаться между различными подключениями к базам данных на лету.

Ищете полностью управляемый удаленный MCP-сервер для MotherDuck? → Перейти к документации по удаленному MCP MotherDuck

Удаленный и локальный MCP

📝 Переходите с версии 0.x?

• Только чтение по умолчанию: Сервер теперь по умолчанию работает в режиме только для чтения. Добавьте --read-write, чтобы включить доступ на запись. См. раздел Защита для продакшена.
• Изменена база данных по умолчанию: Значение по умолчанию для --db-path изменено с md: на :memory:. Добавьте --db-path md: явно для MotherDuck.
• Режим только для чтения MotherDuck требует токен масштабирования чтения: Для подключений MotherDuck в режиме только для чтения требуется токен масштабирования чтения. Для обычных токенов требуется --read-write.

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

Предварительные требования: Установите uv через pip install uv или brew install uv

Подключение к DuckDB в памяти (режим разработки)

{
  "mcpServers": {
    "DuckDB (in-memory, r/w)": {
      "command": "uvx",
      "args": ["mcp-server-motherduck", "--db-path", ":memory:", "--read-write", "--allow-switch-databases"]
    }
  }
}

Полная гибкость без ограничений — доступ на чтение и запись, а также возможность переключения на любую базу данных (локальные файлы, S3 или MotherDuck) во время выполнения.

Подключение к локальному файлу DuckDB в режиме только для чтения

{
  "mcpServers": {
    "DuckDB (read-only)": {
      "command": "uvx",
      "args": ["mcp-server-motherduck", "--db-path", "/absolute/path/to/your.duckdb"]
    }
  }
}

Подключается к определенному файлу DuckDB в режиме только для чтения. Не удерживает блокировку файла, поэтому удобно использовать вместе с подключением на запись к тому же файлу DuckDB. Вы также можете подключаться к удаленным файлам DuckDB на S3, используя s3://bucket/path.duckdb — см. раздел Переменные окружения для аутентификации S3. Если вы рассматриваете сторонний доступ к MCP, см. раздел Защита для продакшена.

Подключение к MotherDuck в режиме чтения-записи

{
  "mcpServers": {
    "MotherDuck (local, r/w)": {
      "command": "uvx",
      "args": ["mcp-server-motherduck", "--db-path", "md:", "--read-write"],
      "env": {
        "motherduck_token": "<YOUR_MOTHERDUCK_TOKEN>"
      }
    }
  }
}

Дополнительные параметры см. в разделе Параметры командной строки, руководство по развертыванию — в разделе Защита для продакшена, а при возникновении проблем — в разделе Устранение неполадок.

Настройка клиента

Клиент	Расположение конфигурации	Установка в один клик
Claude Desktop	Настройки → Разработчик → Редактировать конфигурацию	.mcpb (MCP Bundle)
Claude Code	Используйте команды CLI ниже	-
Codex CLI	Используйте команды CLI ниже или ~/.codex/config.toml	-
Gemini CLI	Используйте команды CLI ниже или ~/.gemini/settings.json	-
Cursor	Настройки → MCP → Добавить новый глобальный MCP-сервер
VS Code	Ctrl+Shift+P → «Настройки: Открыть пользовательские настройки (JSON)»
Kiro	~/.kiro/settings/mcp.json (глобально) или .kiro/settings/mcp.json (проект)

Любой MCP-совместимый клиент может использовать этот сервер. Добавьте JSON-конфигурацию из раздела Быстрый старт в файл конфигурации MCP вашего клиента. Расположение файла конфигурации уточняйте в документации вашего клиента.

claude mcp add --scope user duckdb --transport stdio -- uvx mcp-server-motherduck --db-path :memory: --read-write --allow-switch-databases

claude mcp add --scope user duckdb --transport stdio -- uvx mcp-server-motherduck --db-path /absolute/path/to/db.duckdb

claude mcp add --scope user motherduck --transport stdio --env motherduck_token=YOUR_TOKEN -- uvx mcp-server-motherduck --db-path md: --read-write

codex mcp add duckdb -- uvx mcp-server-motherduck --db-path :memory: --read-write --allow-switch-databases

codex mcp add duckdb -- uvx mcp-server-motherduck --db-path /absolute/path/to/db.duckdb

codex mcp add motherduck --env motherduck_token=YOUR_TOKEN -- uvx mcp-server-motherduck --db-path md: --read-write

gemini mcp add -s user duckdb uvx mcp-server-motherduck --db-path :memory: --read-write --allow-switch-databases

gemini mcp add -s user duckdb uvx mcp-server-motherduck --db-path /absolute/path/to/db.duckdb

gemini mcp add -s user -e motherduck_token=YOUR_TOKEN motherduck uvx mcp-server-motherduck --db-path md: --read-write

{
  "mcpServers": {
    "DuckDB (in-memory, r/w)": {
      "command": "uvx",
      "args": ["mcp-server-motherduck", "--db-path", ":memory:", "--read-write", "--allow-switch-databases"]
    }
  }
}

{
  "mcpServers": {
    "MotherDuck (local, r/w)": {
      "command": "uvx",
      "args": ["mcp-server-motherduck", "--db-path", "md:", "--read-write"],
      "env": {
        "motherduck_token": "<YOUR_MOTHERDUCK_TOKEN>"
      }
    }
  }
}

Инструменты

*Требуется флаг --allow-switch-databases

Все инструменты возвращают JSON. Результаты по умолчанию ограничены 1024 строками / 50 000 символов (настраивается через --max-rows, --max-chars).

Защита для продакшена

При предоставлении сторонним лицам доступа к самостоятельно размещенному MCP-серверу одного режима только для чтения недостаточно — он по-прежнему разрешает доступ к локальной файловой системе, изменение настроек DuckDB и другие потенциально чувствительные операции.

Для продакшен-развертываний со сторонним доступом мы рекомендуем Удаленный MCP MotherDuck — без настройки, с возможностью чтения-записи, размещается MotherDuck.

Самостоятельное размещение MCP MotherDuck: Сделайте форк этого репозитория и настройте по мере необходимости. Используйте сервисный аккаунт с токенами масштабирования чтения и включите режим SaaS, чтобы ограничить доступ к локальным файлам.

Самостоятельное размещение MCP DuckDB: Используйте --init-sql для применения настроек безопасности. Доступные параметры см. в руководстве по защите DuckDB.

Docker

Соберите и запустите сервер с потоковой передачей HTTP на порту 8000 (по умолчанию используется DuckDB в памяти):

docker build -t mcp-server-motherduck .
docker run --rm -p 8000:8000 mcp-server-motherduck

Подключитесь к MotherDuck, передав токен и переопределив команду:

docker run --rm -p 8000:8000 \
  -e motherduck_token="$MOTHERDUCK_TOKEN" \
  mcp-server-motherduck --transport http --db-path md:

Конечная точка MCP доступна по адресу http://localhost:8000/mcp. Флаги командной строки и переменные окружения, указанные ниже, по-прежнему применяются.

Параметры командной строки

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

Устранение неполадок

• spawn uvx ENOENT: Укажите полный путь к uvx (выполните which uvx, чтобы найти его)
• Файл заблокирован: Убедитесь, что --ephemeral-connections включен (по умолчанию: true) и что вы не подключены в режиме чтения-записи

Ресурсы

• Документация MotherDuck MCP
• Close the Loop: Faster Data Pipelines with MCP, DuckDB & AI (Блог)
• Faster Data Pipelines with MCP and DuckDB (YouTube)

Разработка

Для запуска из исходного кода:

{
  "mcpServers": {
    "Local DuckDB (Dev)": {
      "command": "uv",
      "args": ["--directory", "/path/to/mcp-server-motherduck", "run", "mcp-server-motherduck", "--db-path", "md:"],
      "env": {
        "motherduck_token": "<YOUR_MOTHERDUCK_TOKEN>"
      }
    }
  }
}

Процесс выпуска

1. Запустите GitHub Action Release New Version
2. Введите версию в формате MAJOR.MINOR.PATCH
3. Рабочий процесс обновляет версию, публикует в PyPI/реестре MCP и создает релиз GitHub с пакетом MCPB

Лицензия

Лицензия MIT — см. файл LICENSE.

mcp-name: io.github.motherduckdb/mcp-server-motherduck