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

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

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

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

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

📝 Миграция с v0.x? - Только чтение по умолчанию: Сервер теперь по умолчанию работает в режиме только для чтения. Добавьте --read-write для включения доступа на запись. См. Обеспечение безопасности для продакшена. - Изменена база данных по умолчанию: Значение по умолчанию --db-path изменено с md: на :memory:. Явно добавьте --db-path md: для MotherDuck. - Для MotherDuck в режиме только для чтения требуется read-scaling токен: Подключения к MotherDuck в режиме только для чтения требуют read-scaling токен. Обычные токены требуют --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 вашего клиента. Обратитесь к документации вашего клиента для определения местоположения файла конфигурации.

Команды CLI для Claude Code

DuckDB в памяти (Режим разработки):

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

Локальный DuckDB (Только чтение):

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

MotherDuck (Чтение-запись):

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

Команды CLI для Codex

DuckDB в памяти (Режим разработки):

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

Локальный DuckDB (Только чтение):

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

MotherDuck (Чтение-запись):

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

Команды CLI для Gemini

DuckDB в памяти (Режим разработки):

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

Локальный DuckDB (Только чтение):

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

MotherDuck (Чтение-запись):

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

Ручная конфигурация JSON для Kiro

Добавьте следующее в файл конфигурации MCP для Kiro (~/.kiro/settings/mcp.json для глобальной настройки или .kiro/settings/mcp.json для настройки в рамках проекта). Дополнительную информацию см. в документации Kiro MCP.

DuckDB в памяти (Режим разработки):

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

MotherDuck (Чтение-запись):

{
"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: Fork этот репозиторий и настройте его по мере необходимости. Используйте сервисный аккаунт с токенами для масштабирования чтения и включите режим SaaS для ограничения доступа к локальным файлам.

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

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

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

Устранение проблем

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

Ресурсы

• Документация MotherDuck MCP
• Замкните цикл: Более быстрые конвейеры данных с MCP, DuckDB и ИИ (Блог)
• Более быстрые конвейеры данных с MCP и 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-действие Release New Version
2. Введите версию в формате MAJOR.MINOR.PATCH
3. Рабочий процесс увеличивает версию, публикует в PyPI/реестр MCP и создает релиз GitHub с пакетом MCPB

Лицензия

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

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