MCP-сервер DuckDB от MotherDuck

Реализация сервера MCP, взаимодействующая с базами данных DuckDB и MotherDuck, предоставляющая возможности аналитики SQL для помощников ИИ и IDE.

Ресурсы

Related MCP server: Duck Duck MCP

Функции

Гибридное выполнение : запрос данных из локальной базы данных DuckDB и/или облачной базы данных MotherDuck
Интеграция с облачным хранилищем : доступ к данным, хранящимся в Amazon S3 или другом облачном хранилище, благодаря интеграции MotherDuck
Обмен данными : создание и обмен базами данных
Аналитика SQL : используйте диалект SQL DuckDB для запроса любого объема данных непосредственно из вашего AI Assistant или IDE
Архитектура без сервера : запуск аналитики без необходимости настройки экземпляров или кластеров

Компоненты

Подсказки

Сервер выдает одну подсказку:

duckdb-motherduck-initial-prompt : приглашение инициализировать соединение с DuckDB или MotherDuck и начать работу с ним

Инструменты

Сервер предлагает один инструмент:

query : выполнение SQL-запроса к базе данных DuckDB или MotherDuck
- Входные данные :
  - query (строка, обязательно): SQL-запрос для выполнения

Все взаимодействия с DuckDB и MotherDuck осуществляются посредством написания SQL-запросов.

Начиная

Общие предварительные условия

uv установлен, вы можете установить его с помощью pip install uv или brew install uv

Если вы планируете использовать MCP с Claude Desktop или любым другим совместимым с MCP клиентом, необходимо установить клиент.

Предварительные условия для DuckDB

Никаких предварительных условий. Сервер MCP может создавать базу данных в памяти на лету
Или подключитесь к существующему локальному файлу базы данных DuckDB или к файлу, хранящемуся в удаленном хранилище объектов (например, AWS S3).

См. раздел Подключение к локальной DuckDB .

Предпосылки для MotherDuck

Зарегистрируйте учетную запись MotherDuck
Сгенерируйте токен доступа через интерфейс MotherDuck
Сохраните токен в безопасном месте для использования в конфигурации.

Использование с курсором

Установите Cursor с cursor.com/downloads, если вы еще этого не сделали.
Открытый курсор:

Чтобы настроить его глобально в первый раз, перейдите в «Настройки» -> «MCP» и нажмите «+ Добавить новый глобальный сервер MCP».
Откроется файл mcp.json , в который вы добавите следующую конфигурацию:

{ "mcpServers": { "mcp-server-motherduck": { "command": "uvx", "args": [ "mcp-server-motherduck", "--db-path", "md:", "--motherduck-token", "<YOUR_MOTHERDUCK_TOKEN_HERE>" ] } } }

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

Установить с UV в VS Code Установка с UV в VS Code Insiders

Для максимально быстрой установки нажмите одну из кнопок «Установить с UV» в верхней части файла README.

Ручная установка

Добавьте следующий блок JSON в файл настроек пользователя (JSON) в VS Code. Это можно сделать, нажав Ctrl + Shift + P и введя Preferences: Open User Settings (JSON) .

{ "mcp": { "inputs": [ { "type": "promptString", "id": "motherduck_token", "description": "MotherDuck Token", "password": true } ], "servers": { "motherduck": { "command": "uvx", "args": [ "mcp-server-motherduck", "--db-path", "md:", "--motherduck-token", "${input:motherduck_token}" ] } } } }

При желании вы можете добавить его в файл .vscode/mcp.json в вашем рабочем пространстве. Это позволит вам поделиться конфигурацией с другими.

{ "inputs": [ { "type": "promptString", "id": "motherduck_token", "description": "MotherDuck Token", "password": true } ], "servers": { "motherduck": { "command": "uvx", "args": [ "mcp-server-motherduck", "--db-path", "md:", "--motherduck-token", "${input:motherduck_token}" ] } } }

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

Установите Claude Desktop с claude.ai/download , если вы еще этого не сделали.
Откройте файл конфигурации Claude Desktop:

Чтобы быстро получить к нему доступ или создать его в первый раз, откройте приложение Claude Desktop, выберите «Настройки» и нажмите вкладку «Разработчик», затем нажмите кнопку «Изменить конфигурацию».
Добавьте следующую конфигурацию в ваш claude_desktop_config.json :

{ "mcpServers": { "mcp-server-motherduck": { "command": "uvx", "args": [ "mcp-server-motherduck", "--db-path", "md:", "--motherduck-token", "<YOUR_MOTHERDUCK_TOKEN_HERE>" ] } } }

Важные примечания :

Замените YOUR_MOTHERDUCK_TOKEN_HERE на ваш настоящий токен MotherDuck
Замените YOUR_HOME_FOLDER_PATH на путь к вашему домашнему каталогу (необходим DuckDB для файловых операций). Например, на macOS это будет /Users/your_username
Для правильной работы DuckDB необходима переменная среды HOME .

Обеспечение безопасности вашего сервера MCP при запросе MotherDuck

Если сервер MCP доступен третьим лицам и должен иметь доступ только для чтения данных, мы рекомендуем использовать токен масштабирования для чтения и запустить сервер MCP в режиме SaaS.

Токены масштабирования чтения — это специальные токены доступа, которые позволяют масштабировать операции чтения, допуская до 4 одновременных реплик чтения, повышая производительность для нескольких конечных пользователей, ограничивая возможности записи . Обратитесь к документации по масштабированию чтения, чтобы узнать, как создать токен масштабирования чтения.

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

Безопасная конфигурация

{ "mcpServers": { "mcp-server-motherduck": { "command": "uvx", "args": [ "mcp-server-motherduck", "--db-path", "md:", "--motherduck-token", "<YOUR_READ_SCALING_TOKEN_HERE>", "--saas-mode" ] } } }

Подключиться к локальной DuckDB

Чтобы подключиться к локальной базе данных DuckDB, вместо использования токена MotherDuck укажите путь к локальному файлу базы данных DuckDB или используйте :memory: для базы данных в памяти.

База данных в памяти:

{ "mcpServers": { "mcp-server-motherduck": { "command": "uvx", "args": [ "mcp-server-motherduck", "--db-path", ":memory:" ] } } }

Локальный файл DuckDB:

{ "mcpServers": { "mcp-server-motherduck": { "command": "uvx", "args": [ "mcp-server-motherduck", "--db-path", "/path/to/your/local.db" ] } } }

Локальный файл DuckDB в режиме только для чтения :

{ "mcpServers": { "mcp-server-motherduck": { "command": "uvx", "args": [ "mcp-server-motherduck", "--db-path", "/path/to/your/local.db", "--read-only" ] } } }

Примечание : режим только для чтения для локальных файловых подключений DuckDB также использует кратковременные подключения. Каждый раз, когда используется инструмент запроса MCP, создается временное, кратковременное подключение + выполняется запрос + подключение закрывается. Эта функция была мотивирована рабочим процессом, в котором DBT использовался для моделирования данных в duckdb, а затем клиент MCP (Windsurf/Cline/Claude/Cursor) использовался для исследования базы данных. Кратковременные подключения позволяют каждому инструменту запускаться, а затем отключать свое подключение, позволяя подключиться следующему инструменту.

Примеры запросов

После настройки вы можете, например, попросить Клода выполнить такие запросы:

«Создать новую базу данных и таблицу в MotherDuck»
«Запросить данные из моего локального CSV-файла»
«Объединить данные из моей локальной базы данных DuckDB с таблицей в MotherDuck»
«Анализ данных, хранящихся в Amazon S3»

Тестирование

Сервер предназначен для запуска такими инструментами, как Claude Desktop и Cursor, но вы можете запустить его вручную для тестирования. При ручном тестировании сервера вы можете указать, к какой базе данных подключаться, используя параметр --db-path :

База данных MotherDuck по умолчанию :
- Чтобы подключиться к базе данных MotherDuck по умолчанию, вам необходимо передать токен аутентификации с помощью параметра --motherduck-token .
uvx mcp-server-motherduck --db-path md: --motherduck-token <your_motherduck_token>
Конкретная база данных MotherDuck :
uvx mcp-server-motherduck --db-path md:your_database_name --motherduck-token <your_motherduck_token>
Локальная база данных DuckDB :
uvx mcp-server-motherduck --db-path /path/to/your/local.db
База данных в памяти :
uvx mcp-server-motherduck --db-path :memory:

Если вы не указали путь к базе данных, но установили переменную среды motherduck_token , сервер автоматически подключится к базе данных MotherDuck по умолчанию ( md: ).

Работа в режиме SSE

Сервер также может работать в режиме SSE с использованием supergateway , если выполнить следующую команду:

npx -y supergateway --stdio "uvx mcp-server-motherduck --db-path md: --motherduck-token <your_motherduck_token>"

И вы можете направить свои клиенты, такие как Claude Desktop, Cursor, на эту конечную точку.

Конфигурация разработки

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

{ "mcpServers": { "mcp-server-motherduck": { "command": "uv", "args": [ "--directory", "/path/to/your/local/mcp-server-motherduck", "run", "mcp-server-motherduck", "--db-path", "md:", "--motherduck-token", "<YOUR_MOTHERDUCK_TOKEN_HERE>" ] } } }

Поиск неисправностей

Если у вас возникли проблемы с подключением, проверьте правильность токена MotherDuck.
При проблемах с доступом к локальным файлам убедитесь, что параметр --home-dir установлен правильно.
Проверьте, доступна ли команда uvx в вашем PATH.
Если вы столкнулись с ошибками spawn uvx ENOENT , попробуйте указать полный путь к uvx (вывод which uvx )
В предыдущей версии v0.4.0 мы использовали переменные окружения, теперь мы используем параметры

Лицензия

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

mcp-server-motherduck