MotherDuck

DuckDB / MotherDuck Local MCP Server

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

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

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

Remote vs Local MCP

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

Предварительные требования: Установите 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 → "Preferences: Open User Settings (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 и другие потенциально чувствительные операции.

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

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

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

Docker

Соберите и запустите сервер с Streamable 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. Флаги CLI и переменные окружения из приведенного ниже по-прежнему применяются.

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

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

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

• 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 registry и создает GitHub-релиз с пакетом MCPB

Лицензия

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

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