Keboola MCP Server

официальный

Создавайте надежные рабочие процессы с данными, интеграции и аналитику на единой интуитивно понятной платформе.

Документация

Keboola MCP-сервер

Подключите ваших AI-агентов, MCP-клиенты (Cursor, Claude, Windsurf, VS Code ...) и других AI-ассистентов к Keboola. Предоставляйте данные, трансформации, SQL-запросы и триггеры заданий — без связующего кода. Доставляйте нужные данные агентам тогда и там, где они необходимы.

Обзор

Keboola MCP-сервер — это мост с открытым исходным кодом между вашим проектом Keboola и современными AI-инструментами. Он превращает функции Keboola — такие как доступ к хранилищу, SQL-трансформации и триггеры заданий — в вызываемые инструменты для Claude, Cursor, CrewAI, LangChain, Amazon Q и других.

Быстрый старт
Локальная настройка

Возможности

С AI-агентом и MCP-сервером вы можете:

Хранилище: Напрямую запрашивать таблицы и управлять описаниями таблиц или бакетов
Компоненты: Создавать, просматривать и изучать конфигурации экстракторов, писателей, дата-приложений и трансформаций
SQL: Создавать SQL-трансформации на естественном языке
Задания: Запускать компоненты и трансформации, а также получать детали выполнения заданий
Потоки: Строить и управлять пайплайнами рабочих процессов с помощью условных потоков и потоков оркестратора.
Дата-приложения: Создавать, развертывать и управлять дата-приложениями Keboola Streamlit, отображающими ваши запросы к данным хранилища.
Метаданные: Искать, читать и обновлять документацию проекта и метаданные объектов на естественном языке
Ветки разработки: Безопасно работать в ветках разработки вне продакшена, где все операции ограничены выбранной веткой.

🚀 Быстрый старт: Удаленный MCP-сервер (Самый простой способ)

Самый простой способ использовать Keboola MCP-сервер — через наш Удаленный MCP-сервер. Это размещенное решение избавляет от необходимости локальной настройки, конфигурации или установки.

Что такое Удаленный MCP-сервер?

Наш удаленный сервер размещен на каждом мультитенантном стеке Keboola и поддерживает OAuth-аутентификацию. Вы можете подключиться к нему из любого AI-ассистента, поддерживающего удаленное потоковое HTTP-соединение и OAuth-аутентификацию.

Как подключиться

Получите URL вашего удаленного сервера: Перейдите в Настройки проекта Keboola → вкладка MCP Server
Скопируйте URL сервера: Он будет выглядеть как https://mcp.<YOUR_REGION>.keboola.com/mcp
Настройте вашего AI-ассистента: Вставьте URL в настройки MCP вашего AI-ассистента
Аутентифицируйтесь: Вам будет предложено войти в вашу учетную запись Keboola и выбрать проект

Поддерживаемые клиенты

Cursor: Используйте кнопку «Установить в Cursor» в настройках MCP-сервера вашего проекта или нажмите эту кнопку
Claude Desktop: Добавьте интеграцию через Настройки → Интеграции
Claude Code: Установите с помощью claude mcp add --transport http keboola <URL> (подробности см. ниже)
Windsurf: Настройте с URL удаленного сервера
Make: Настройте с URL удаленного сервера
Другие MCP-клиенты: Настройте с URL удаленного сервера

Настройка Claude Code

Claude Code — это инструмент командной строки, позволяющий взаимодействовать с Claude через терминал. Вы можете установить интеграцию Keboola MCP-сервера с помощью простой команды.

Установка:

Выполните следующую команду в терминале, заменив <YOUR_REGION> на ваш регион Keboola:

claude mcp add --transport http keboola https://mcp.<YOUR_REGION>.keboola.com/mcp

Команды для конкретных регионов:

Регион	Команда установки
US Virginia AWS	`claude mcp add --transport http keboola https://mcp.keboola.com/mcp`
US Virginia GCP	`claude mcp add --transport http keboola https://mcp.us-east4.gcp.keboola.com/mcp`
EU Frankfurt AWS	`claude mcp add --transport http keboola https://mcp.eu-central-1.keboola.com/mcp`
EU Ireland Azure	`claude mcp add --transport http keboola https://mcp.north-europe.azure.keboola.com/mcp`
EU Frankfurt GCP	`claude mcp add --transport http keboola https://mcp.europe-west3.gcp.keboola.com/mcp`

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

После установки вы можете использовать Keboola MCP-сервер в Claude Code, введя /mcp в вашем разговоре и выбрав инструменты Keboola, которые хотите использовать.

Аутентификация:

При первом использовании Keboola MCP-сервера в Claude Code откроется окно браузера с предложением:

Войти в вашу учетную запись Keboola
Выбрать проект, к которому хотите подключиться
Авторизовать подключение

После аутентификации вы сможете использовать инструменты Keboola напрямую из Claude Code.

Подробные инструкции по настройке и URL для конкретных регионов см. в нашей документации по настройке удаленного сервера.

Использование веток разработки

Вы можете безопасно работать в ветках разработки Keboola, не затрагивая производственные данные. Удаленно размещенные MCP-серверы учитывают параметр KBC_BRANCH_ID и ограничивают все операции указанной веткой. Идентификатор ветки разработки можно найти в URL при переходе к ветке разработки в пользовательском интерфейсе, например: https://connection.us-east4.gcp.keboola.com/admin/projects/PROJECT_ID/branch/BRANCH_ID/dashboard. Идентификатор ветки должен быть включен в каждый запрос с помощью заголовка X-Branch-Id: <branchId>, иначе MCP-сервер по умолчанию использует производственную ветку. Это должно управляться AI-клиентом или окружением, обрабатывающим подключение к серверу.

Авторизация инструментов и контроль доступа

При использовании транспорта на основе HTTP (потоковый HTTP) вы можете контролировать, какие инструменты доступны клиентам, с помощью HTTP-заголовков. Это полезно для ограничения возможностей AI-агентов или обеспечения соблюдения политик.

Заголовки авторизации

Заголовок	Описание	Пример
`X-Allowed-Tools`	Список разрешенных инструментов через запятую	`get_configs,get_buckets,query_data`
`X-Disallowed-Tools`	Список инструментов для исключения через запятую	`create_config,run_job`
`X-Read-Only-Mode`	Ограничить только инструментами только для чтения	`true`, `1` или `yes`

Поведение фильтра

Фильтры применяются по порядку: разрешенные → пересечение только для чтения → исключение запрещенных. Пустые заголовки = без ограничений.

Инструменты только для чтения

Инструменты только для чтения — это те, которые аннотированы readOnlyHint=True. Эти инструменты только извлекают информацию, не внося изменений в ваш проект Keboola. Актуальный список инструментов только для чтения см. в файле TOOLS.md, который является автоматически сгенерированным снимком фактического набора инструментов.

Пример: Доступ только для чтения

X-Read-Only-Mode: true

Подробную документацию см. на developers.keboola.com/integrate/mcp/#tool-authorization-and-access-control.

Локальная настройка MCP-сервера (Пользовательский способ или способ разработчика)

Запустите MCP-сервер на своей машине для полного контроля и удобной разработки. Выбирайте этот вариант, если хотите настраивать инструменты, отлаживать локально или быстро итерировать. Вы клонируете репозиторий, устанавливаете учетные данные Keboola через переменные окружения или заголовки в зависимости от транспорта сервера, устанавливаете зависимости и запускаете сервер. Этот подход предлагает максимальную гибкость (пользовательские инструменты, локальное логирование, офлайн-итерация), но требует ручной настройки, и вы сами управляете обновлениями и секретами.

Сервер поддерживает несколько вариантов транспорта, которые можно выбрать, указав аргумент --transport <transport> при запуске сервера:

stdio - По умолчанию, если --transport не указан. Стандартный ввод/вывод, обычно используется для локального развертывания с одним клиентом.
streamable-http - Запускает сервер удаленно через HTTP с двунаправленным потоковым каналом, позволяя клиенту и серверу непрерывно обмениваться сообщениями. Подключайтесь через /mcp (например, http://localhost:8000/mcp).
http-compat - Псевдоним для streamable-http, сохранен для обратной совместимости.

Для связи клиент-сервер необходимо предоставить учетные данные Keboola, чтобы обеспечить работу с вашим проектом в вашем регионе Keboola. Требуются следующие: KBC_STORAGE_TOKEN, KBC_STORAGE_API_URL, KBC_WORKSPACE_SCHEMA и опционально KBC_BRANCH_ID. Вы можете предоставить их двумя способами:

Для личного использования (в основном с транспортом stdio): установите переменные окружения перед запуском сервера. Все запросы будут повторно использовать эти предопределенные учетные данные.
Для многопользовательского использования: включите переменные в заголовки запроса, чтобы каждый запрос использовал предоставленные с ним учетные данные.

KBC_STORAGE_TOKEN

Это ваш токен аутентификации для Keboola:

Инструкции по созданию и управлению токенами Storage API см. в официальной документации Keboola.

Примечание: Если вы хотите, чтобы MCP-сервер имел ограниченный доступ, используйте пользовательский токен хранилища; если вы хотите, чтобы MCP имел доступ ко всему в вашем проекте, используйте мастер-токен.

KBC_WORKSPACE_SCHEMA

Это идентифицирует ваше рабочее пространство в Keboola и используется для SQL-запросов. Однако это требуется только при использовании пользовательского токена хранилища вместо мастер-токена:

При использовании Мастер-токена: Рабочее пространство создается автоматически в фоновом режиме
При использовании пользовательского токена хранилища: Следуйте этому руководству Keboola, чтобы получить ваш KBC_WORKSPACE_SCHEMA

Примечание: При создании рабочего пространства вручную отметьте опцию «Предоставить доступ только для чтения ко всем данным проекта»

Примечание: KBC_WORKSPACE_SCHEMA называется «Имя набора данных» в рабочих пространствах BigQuery; просто нажмите «Подключиться» и скопируйте имя набора данных

KBC_STORAGE_API_URL (Регион Keboola)

URL API вашего региона Keboola зависит от региона развертывания. Вы можете определить свой регион, посмотрев на URL в браузере при входе в ваш проект Keboola:

Регион	URL API
AWS Северная Америка	`https://connection.keboola.com`
AWS Европа	`https://connection.eu-central-1.keboola.com`
Google Cloud EU	`https://connection.europe-west3.gcp.keboola.com`
Google Cloud US	`https://connection.us-east4.gcp.keboola.com`
Azure EU	`https://connection.north-europe.azure.keboola.com`

KBC_BRANCH_ID (Опционально)

Для работы в конкретной ветке разработки Keboola установите идентификатор ветки с помощью параметра KBC_BRANCH_ID. MCP-сервер ограничивает свою функциональность указанной веткой, гарантируя, что все изменения остаются изолированными и не влияют на производственную ветку.

Если не указано, сервер по умолчанию использует производственную ветку.
Для работы над разработкой установите KBC_BRANCH_ID в числовой идентификатор вашей ветки (например, 123456). Идентификатор ветки разработки можно найти в URL при переходе к ветке разработки в пользовательском интерфейсе, например: https://connection.us-east4.gcp.keboola.com/admin/projects/PROJECT_ID/branch/BRANCH_ID/dashboard.
На удаленных транспортах вы можете переопределить для каждого запроса с помощью HTTP-заголовка X-Branch-Id: <branchId> или KBC_BRANCH_ID: <branchId>.

Установка

Убедитесь, что у вас есть:

Установлен Python 3.10+
Доступ к проекту Keboola с правами администратора
Предпочитаемый MCP-клиент (Claude, Cursor и т.д.)

Примечание: Убедитесь, что у вас установлен uv. MCP-клиент будет использовать его для автоматической загрузки и запуска Keboola MCP-сервера. Установка uv:

macOS/Linux:

#if homebrew is not installed on your machine use:
# /bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"

# Install using Homebrew
brew install uv

Windows:

# Using the installer script
powershell -ExecutionPolicy ByPass -c "irm https://astral.sh/uv/install.ps1 | iex"

# Or using pip
pip install uv

# Or using winget
winget install --id=astral-sh.uv -e

Дополнительные варианты установки см. в официальной документации uv.

Запуск Keboola MCP-сервера

Существует четыре способа использования Keboola MCP-сервера, в зависимости от ваших потребностей:

Вариант A: Интегрированный режим (Рекомендуется)

В этом режиме Claude или Cursor автоматически запускает MCP-сервер за вас. Вам не нужно выполнять какие-либо команды в терминале.

Настройте ваш MCP-клиент (Claude/Cursor) с соответствующими параметрами
Клиент автоматически запустит MCP-сервер при необходимости

Конфигурация Claude Desktop

Перейдите в Claude (верхний левый угол экрана) -> Настройки → Разработчик → Редактировать конфигурацию (если вы не видите claude_desktop_config.json, создайте его)
Добавьте следующую конфигурацию:
Перезапустите Claude Desktop, чтобы изменения вступили в силу

{
  "mcpServers": {
    "keboola": {
      "command": "uvx",
      "args": ["keboola_mcp_server --transport <transport>"],
      "env": {
        "KBC_STORAGE_API_URL": "https://connection.YOUR_REGION.keboola.com",
        "KBC_STORAGE_TOKEN": "your_keboola_storage_token",
        "KBC_WORKSPACE_SCHEMA": "your_workspace_schema",
        "KBC_BRANCH_ID": "your_branch_id_optional"
      }
    }
  }
}

Расположение файлов конфигурации:

macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
Windows: %APPDATA%\Claude\claude_desktop_config.json

Конфигурация Cursor

Перейдите в Настройки → MCP
Нажмите «+ Добавить новый глобальный MCP-сервер»
Настройте со следующими параметрами:

{
  "mcpServers": {
    "keboola": {
      "command": "uvx",
      "args": ["keboola_mcp_server --transport <transport>"],
      "env": {
        "KBC_STORAGE_API_URL": "https://connection.YOUR_REGION.keboola.com",
        "KBC_STORAGE_TOKEN": "your_keboola_storage_token",
        "KBC_WORKSPACE_SCHEMA": "your_workspace_schema",
        "KBC_BRANCH_ID": "your_branch_id_optional"
      }
    }
  }
}

Примечание: Используйте короткие, описательные имена для MCP-серверов. Поскольку полное имя инструмента включает имя сервера и должно быть не длиннее ~60 символов, более длинные имена могут быть отфильтрованы в Cursor и не будут отображаться агенту.

Конфигурация Cursor для Windows WSL

При запуске MCP-сервера из Windows Subsystem for Linux с Cursor AI используйте эту конфигурацию:

{
  "mcpServers": {
    "keboola":{
      "command": "wsl.exe",
      "args": [
          "bash",
          "-c '",
          "export KBC_STORAGE_API_URL=https://connection.YOUR_REGION.keboola.com &&",
          "export KBC_STORAGE_TOKEN=your_keboola_storage_token &&",
          "export KBC_WORKSPACE_SCHEMA=your_workspace_schema &&",
          "export KBC_BRANCH_ID=your_branch_id_optional &&",
          "/snap/bin/uvx keboola_mcp_server --transport <transport>",
          "'"
      ]
    }
  }
}

Вариант B: Режим локальной разработки

Для разработчиков, работающих над самим кодом MCP-сервера:

Клонируйте репозиторий и настройте локальное окружение
Настройте Claude/Cursor на использование вашего локального пути Python:

{
  "mcpServers": {
    "keboola": {
      "command": "/absolute/path/to/.venv/bin/python",
      "args": [
        "-m",
        "keboola_mcp_server --transport <transport>"
      ],
      "env": {
        "KBC_STORAGE_API_URL": "https://connection.YOUR_REGION.keboola.com",
        "KBC_STORAGE_TOKEN": "your_keboola_storage_token",
        "KBC_WORKSPACE_SCHEMA": "your_workspace_schema",
        "KBC_BRANCH_ID": "your_branch_id_optional"
      }
    }
  }
}

Вариант C: Ручной режим CLI (только для тестирования)

Вы можете запустить сервер вручную в терминале для тестирования или отладки:

# Set environment variables
export KBC_STORAGE_API_URL=https://connection.YOUR_REGION.keboola.com
export KBC_STORAGE_TOKEN=your_keboola_storage_token
export KBC_WORKSPACE_SCHEMA=your_workspace_schema
export KBC_BRANCH_ID=your_branch_id_optional

uvx keboola_mcp_server --transport streamable-http

Примечание: Этот режим предназначен в первую очередь для отладки или тестирования. Для обычного использования с Claude или Cursor вам не нужно запускать сервер вручную.

Примечание: Сервер будет использовать транспорт Streamable HTTP и слушать на localhost:8000 входящие соединения по адресу /mcp. Вы можете использовать параметры --port и --host, чтобы заставить его слушать в другом месте.

Вариант D: Использование Docker

docker pull keboola/mcp-server:latest

docker run \
  --name keboola_mcp_server \
  --rm \
  -it \
  -p 127.0.0.1:8000:8000 \
  -e KBC_STORAGE_API_URL="https://connection.YOUR_REGION.keboola.com" \
  -e KBC_STORAGE_TOKEN="YOUR_KEBOOLA_STORAGE_TOKEN" \
  -e KBC_WORKSPACE_SCHEMA="YOUR_WORKSPACE_SCHEMA" \
  -e KBC_BRANCH_ID="YOUR_BRANCH_ID_OPTIONAL" \
  keboola/mcp-server:latest \
  --transport streamable-http \
  --host 0.0.0.0

Примечание: Сервер будет использовать транспорт Streamable HTTP и слушать на localhost:8000 входящие соединения по адресу /mcp. Вы можете изменить -p, чтобы сопоставить порт контейнера с другим портом.

Нужно ли мне запускать сервер самостоятельно?

Сценарий	Нужен ручной запуск?	Используйте эту настройку
Использование Claude/Cursor	Нет	Настройте MCP в параметрах приложения
Локальная разработка MCP	Нет (Claude запускает его)	Укажите в конфигурации путь к python
Ручное тестирование CLI	Да	Используйте терминал для запуска
Использование Docker	Да	Запустите docker-контейнер

Использование MCP-сервера

После того как ваш MCP-клиент (Claude/Cursor) настроен и запущен, вы можете начать запрашивать ваши данные Keboola:

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

Вы можете начать с простого запроса, чтобы убедиться, что всё работает:

What buckets and tables are in my Keboola project?

Примеры того, что вы можете делать

Исследование данных:

"Какие таблицы содержат информацию о клиентах?"
"Выполни запрос, чтобы найти топ-10 клиентов по выручке"

Анализ данных:

"Проанализируй мои данные о продажах по регионам за последний квартал"
"Найди корреляции между возрастом клиентов и частотой покупок"

Конвейеры данных:

"Создай SQL-трансформацию, которая объединяет таблицы клиентов и заказов"
"Запусти задание извлечения данных для моего компонента Salesforce"

Совместимость

Поддержка MCP-клиентов

MCP-клиент	Статус поддержки	Метод подключения
Claude (Desktop и Web)	✅ поддерживается	stdio
Cursor	✅ поддерживается	stdio
Windsurf, Zed, Replit	✅ Поддерживается	stdio
Codeium, Sourcegraph	✅ Поддерживается	Streamable HTTP
Пользовательские MCP-клиенты	✅ Поддерживается	Streamable HTTP или stdio

Поддерживаемые инструменты

Примечание: Ваши AI-агенты будут автоматически адаптироваться к новым инструментам.

Полный список доступных инструментов с подробными описаниями, параметрами и примерами использования см. в TOOLS.md.

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

Распространенные проблемы

Проблема	Решение
Ошибки аутентификации	Проверьте, действителен ли `KBC_STORAGE_TOKEN`
Проблемы с рабочим пространством	Убедитесь, что `KBC_WORKSPACE_SCHEMA` корректен
Тайм-аут соединения	Проверьте сетевое подключение

Разработка

Установка

Базовая настройка:

uv sync --extra dev

При базовой настройке вы можете использовать uv run tox для запуска тестов и проверки стиля кода.

Рекомендуемая настройка:

uv sync --extra dev --extra tests --extra integtests --extra codestyle

При рекомендуемой настройке будут установлены пакеты для тестирования и проверки стиля кода, что позволяет IDE, таким как VsCode или Cursor, проверять код или запускать тесты во время разработки.

Интеграционные тесты

Для локального запуска интеграционных тестов используйте uv run tox -e integtests. ПРИМЕЧАНИЕ: Вам потребуется установить следующие переменные окружения:

INTEGTEST_POOL_STORAGE_API_URL
INTEGTEST_STORAGE_TOKENS
INTEGTEST_STORAGE_TOKEN_STORAGE_BRANCHES

Для получения этих значений вам понадобятся выделенные проекты Keboola для интеграционных тестов. Каждый тестовый сеанс создает собственное рабочее пространство только для чтения, поэтому схему рабочего пространства настраивать не нужно. Подробные инструкции по настройке и проектную документацию см. в integtests/README.md.

Обновление `uv.lock`

Обновите файл uv.lock, если вы добавили или удалили зависимости. Также рассмотрите возможность обновления lock-файла с более новыми версиями зависимостей при создании релиза (uv lock --upgrade).

Обновление документации по инструментам

При внесении изменений в описания любых инструментов (docstring в функциях инструментов) необходимо заново сгенерировать файл документации TOOLS.md, чтобы отразить эти изменения:

uv run python -m src.keboola_mcp_server.generate_tool_docs

Релиз

Мы не делаем релиз для каждого слитого PR. Изменения непрерывно попадают в основную ветку (main), и мы выпускаем релизы периодически, после того как изменения будут повторно протестированы вместе — это позволяет избежать поломки работающих конфигураций у пользователей.

Релиз создается путем отправки одного или двух git-тегов:

vX.Y.Z — релиз MCP-сервера (всегда)
agent-vX.Y.Z — релиз In Platform Agent (только когда агент также выпускается)

Любой из тегов запускает CI release.yml, который собирает и публикует образ Docker. KaiBench запускается только на production-тегах vX.Y.Z (не на agent-vX.Y.Z и не на пре-релизах -dev.). Используйте навык release-notes — он подготавливает заметки о релизе и черновик PR, а также проводит через процесс тегирования как vX.Y.Z, так и agent-vX.Y.Z.

Поддержка и обратная связь

⭐ Основной способ получить помощь, сообщить об ошибках или запросить новые функции — создать issue на GitHub. ⭐

Команда разработчиков активно отслеживает issues и ответит как можно быстрее. Для общей информации о Keboola, пожалуйста, используйте ресурсы ниже.

Ресурсы

Пользовательская документация
Документация для разработчиков
Платформа Keboola
Трекер задач ← Основной способ связи по MCP-серверу

Keboola MCP Server

Документация

Keboola MCP-сервер

Обзор

Возможности

🚀 Быстрый старт: Удаленный MCP-сервер (Самый простой способ)

Что такое Удаленный MCP-сервер?

Как подключиться

Поддерживаемые клиенты

Настройка Claude Code

Использование веток разработки

Авторизация инструментов и контроль доступа

Заголовки авторизации

Поведение фильтра

Инструменты только для чтения

Пример: Доступ только для чтения

Локальная настройка MCP-сервера (Пользовательский способ или способ разработчика)

KBC_STORAGE_TOKEN

KBC_WORKSPACE_SCHEMA

KBC_STORAGE_API_URL (Регион Keboola)

KBC_BRANCH_ID (Опционально)

Установка

Запуск Keboola MCP-сервера

Вариант A: Интегрированный режим (Рекомендуется)

Конфигурация Claude Desktop

Конфигурация Cursor

Конфигурация Cursor для Windows WSL

Вариант B: Режим локальной разработки

Вариант C: Ручной режим CLI (только для тестирования)

Вариант D: Использование Docker

Нужно ли мне запускать сервер самостоятельно?

Использование MCP-сервера

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

Примеры того, что вы можете делать

Совместимость

Поддержка MCP-клиентов

Поддерживаемые инструменты

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

Распространенные проблемы

Разработка

Установка

Интеграционные тесты

Обновление uv.lock

Обновление документации по инструментам

Релиз

Поддержка и обратная связь

Ресурсы

Связь

Обновление `uv.lock`