mcp-server-motherduck

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

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

Ресурсы

• Замкните цикл: более быстрые конвейеры данных с MCP, DuckDB и ИИ (запись в блоге)
• Более быстрая разработка конвейеров данных с помощью MCP и DuckDB (YouTube)

Функции

• Гибридное выполнение : запрос данных из локальной базы данных 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
• Сохраните токен в безопасном месте для использования в конфигурации.

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

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

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

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

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

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

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

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

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

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

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

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

• Замените 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 .

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

Лицензия

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