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