Keboola

MCP-сервер Keboola

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

Обзор

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

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

Возможности

С помощью ИИ-агента и MCP-сервера вы можете:

• Хранилище: напрямую запрашивать таблицы и управлять описаниями таблиц и бакетов
• Компоненты: создавать, просматривать и изучать конфигурации экстракторов, записывающих компонентов, приложений для работы с данными и преобразований
• SQL: создавать SQL-преобразования на естественном языке
• Задания: запускать компоненты и преобразования, а также получать сведения о выполнении заданий
• Потоки: создавать и управлять конвейерами рабочих процессов с помощью Conditional Flows и Orchestrator Flows.
• Приложения для работы с данными: создавать, развёртывать и управлять приложениями Keboola Data Apps, отображающими результаты запросов к данным хранилища — приложениями python-js в репозитории под управлением Keboola или в репозитории GitHub клиента (клонируемом через подключение GitHub организации, без сохранения учётных данных), а также приложениями Streamlit.
• Метаданные: искать, читать и обновлять документацию проекта и метаданные объектов на естественном языке
• Ветки разработки: безопасно работать в ветках разработки вне производственной среды, где все операции ограничены выбранной веткой.

---

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

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

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

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

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

1. Получите URL удалённого сервера: перейдите в настройки проекта Keboola → вкладка MCP Server
2. Скопируйте URL сервера: он будет выглядеть так: https://mcp.<YOUR_REGION>.keboola.com/mcp
3. Настройте ИИ-ассистента: вставьте URL в настройки MCP вашего ИИ-ассистента
4. Пройдите аутентификацию: вам будет предложено войти в учётную запись Keboola. Выбор проекта или проектов для работы выполняется позже, в ходе беседы (например, «покажи мои проекты Keboola» / «используй проект X»)

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

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

Настройка Claude Code

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

Установка:

Выполните в терминале следующую команду, заменив <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

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

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

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

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

1. Войти в учётную запись Keboola
2. Разрешить подключение

После аутентификации вы сможете использовать инструменты Keboola непосредственно из Claude Code. Выбор проекта выполняется позже, в ходе беседы — просто спросите Claude, с каким проектом или проектами Keboola работать.

Подробные инструкции по настройке и 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-сервер по умолчанию использует производственную ветку. Это должен обеспечивать ИИ-клиент или среда, управляющая подключением к серверу.

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

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

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

Заголовок	Описание	Пример
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

Отложенная загрузка инструментов

Заголовок	Описание	Пример
X-Deferred-Tools	Список инструментов, разделённых запятыми, которые нужно перечислить с помощью _meta["anthropic/alwaysLoad"] = false	run_sync_action,get_flow_schema

Клиенты Claude Code / Claude Agent SDK, регистрирующие сервер с помощью alwaysLoad: true, оставляют эти инструменты отложенными и предоставляют их через поиск инструментов, вместо того чтобы загружать их описания заранее. Заголовок изменяет только метаданные tools/list — он не скрывает инструменты и не управляет доступом к ним. Пустой заголовок или неизвестные имена инструментов не приводят к изменениям.

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

Безопасность на уровне строк и столбцов

Политики на уровне строк и столбцов — это объекты Keboola Metastore (rls-policy, cls-policy), записываемые через API Metastore (команды kbagent rls / kbagent cls пока не входят ни в один выпуск kbagent). Этот сервер не считывает и не применяет их. В проекте, где включена функция row-level-security, он создаёт рабочую область (конфигурацию mcp-workspace-<hex> компонента keboola.mcp-server-tool) с типом входа Connection governed. У управляемой рабочей области нет учётных данных: читать её может только Query Service, который фильтрует каждый результат query_data в соответствии с политиками проекта. Этот сервер не переписывает запросы и не использует резервный вариант: если Query Service отказывает в доступе, query_data возвращает ошибку.

• Что включает эту функцию. Функцию проекта проверяет только этот сервер; Connection не нужны ни функция, ни роль, чтобы создать управляемую рабочую область (Snowflake или BigQuery, без открытого ключа). Connection стека должен принимать тип входа governed для серверной части проекта: стек, который этого не делает, отклоняет создание, после чего все инструменты, которым нужна рабочая область, завершаются с ошибкой (перехода к обычной рабочей области нет). Сквозная проверка принудительного применения политик в BigQuery на рабочем стеке не проводилась. Старая обычная рабочая область MCP не удаляется: после включения функции она пропускается. При включённой функции привязка workspace_schema или X-Workspace-Id принимается только для управляемой рабочей области (обычная позволила бы обойти политики), поэтому привязка к старой рабочей области или к собственной обычной рабочей области приложения данных отклоняется; удалите старую рабочую область.
• Запрет по умолчанию. Таблица, на которую не распространяется ни rls-policy, ни cls-policy, недоступна администратору (агент получает Row-level security does not allow this query), а для обычного читателя, например конечного пользователя приложения данных, возвращает ноль строк ("*" открывает таблицу для всех идентифицированных читателей). Один только cls-policy открывает свою таблицу: все строки, только указанные столбцы, для названных в нём читателей; всем остальным читателям доступ запрещён. Выполняется оператор, который не читает таблиц (SELECT 1).
• Отклоняемые операторы. Управляемый оператор отклоняется (403, одинаковый общий текст для всех причин), если он использует IDENTIFIER(), TABLE() вне FROM, функцию ИИ (AI_*, BigQuery AI.*), TO_FILE, READ_CSV / READ_PARQUET, SECRET, функцию контекста сеанса (CURRENT_USER, CURRENT_ROLE, CURRENT_STATEMENT, ...), NEXTVAL, $x или @@x, управляющий символ либо имя без кавычек с символом не ASCII или $$, а также если его размер превышает 32 KiB, в нём более 200 CTE или 300 ссылок на таблицы. CURRENT_DATE, CURRENT_TIME и CURRENT_TIMESTAMP остаются разрешёнными (в Query Service 1.25 и policy engine 0.1.8). Ошибка 503 Row-level security could not be applied to this workspace означает, что ничего не было выполнено, поскольку политики не удалось применить; ошибка может быть временной. Ошибка управляемого оператора возвращает The statement failed. Its error text is not shown for a workspace with row-level security.
• Кто является читателем. Query Service определяет читателя по собственному токену администратора проекта: программному токену, который пересылает этот сервер (kbc_at_ / kbc_pat_, включая дочерний PAT области с несколькими проектами, отправленный с X-KBC-ProjectId), либо собственному главному токену Storage администратора. Любой другой токен (интеграции, приложения данных, Kai) не указывает конечного пользователя, не имеет подтверждённой личности и не читает данные из управляемой таблицы. Субъект администратора — keboola|<adminId>, а идентификатор не содержит групп, поэтому правила для групп никогда не срабатывают.
• Привязки. Без привязки рабочая область получает все политики проекта, а этот сервер никогда не создаёт привязки. Чтобы предоставить рабочей области только некоторые политики, привяжите их к её KID: KID:<stack-id>:project-<project-id>:workspace-<workspace-id> (рабочая область ветки по умолчанию; у рабочей области ветки также есть branch-<branch-id> перед project). Идентификатор стека — тот, с которым настроен Query Service (QUERY_RLS_STACK_ID, например dev-keboola-aws-eu-west-1), идентификатор рабочей области указан в выводе get_project_info, а объект Metastore типа policy-binding с этим KID записывает привязку (команда kbagent для этого пока не выпущена). Привязка — это список разрешений: она сохраняет только перечисленные в ней политики, поэтому может исключить любую политику, в том числе уровня организации, и ослабить контроль доступа. Если в ней не указано ни одного rls-policy, удаляются все политики строк, поэтому таблица, на которую распространяется сохранённый cls-policy, открывается со всеми строками. Привязка применяется к следующему запросу и не переносится вместе с сеансом в другую рабочую область: сеанс ветки или пересозданная рабочая область получает новый KID и снова начинает со всеми политиками.
• Ограничения. Идентификатор рабочей области сервера — это также значение, которое приложение данных получает как WORKSPACE_ID, если для него не выделена отдельная рабочая область; приложение выполняет запросы со своим токеном, не имеет подтверждённой личности и не читает данные из управляемых таблиц.
• Метаданные. Инструменты метаданных показывают только то, что Query Service разрешает читать данному читателю. get_tables и search (который в этом случае не использует глобальный поиск, поскольку его счётчики включают скрытые таблицы) не показывают таблицу, которую читателю читать нельзя, а get_tables сообщает, что таблица, запрошенная по ID, не найдена; у таблицы с политикой столбцов отображаются только столбцы, разрешённые политикой (также в первичном ключе и при сопоставлении с помощью search). Читаемая таблица отображается без количества строк и размера, поскольку эти значения учитывают строки, скрытые политикой строк. get_buckets по-прежнему перечисляет все бакеты, но без количества таблиц и размера, поскольку эти значения учитывают скрытые таблицы. Для этого требуется конечная точка Query Service POST /api/v1/branches/{branch}/workspaces/{workspace}/rls/scope, и при сбое доступ закрывается: если Query Service не может дать ответ, инструмент управляемого проекта возвращает ошибку с коротким сообщением и без таблицы. Проекты без этой функции не затрагиваются и не выполняют дополнительных запросов.

---

Настройка локального MCP-сервера (пользовательский вариант или для разработки)

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

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

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

Для работы с проектом Keboola серверу нужны две вещи: ваш регион Keboola (KBC_STORAGE_API_URL) и способ аутентификации. Рекомендуемый способ — однократный вход через браузер: создавать, копировать или вставлять токен не нужно. При необходимости задайте KBC_BRANCH_ID, чтобы работать в ветке разработки.

Некоторые переменные не берутся из заголовков запроса:

• KBC_STORAGE_API_URL: сервер, запущенный с собственным URL Storage API (параметр --api-url или переменная среды KBC_STORAGE_API_URL), обслуживает только этот стек Keboola. Заголовок X-Storage-Api-Url, запрашивающий другой хост, игнорируется (в журнал записывается предупреждение) — сервер использует для запроса собственный URL. Если вы хотите, чтобы каждый запрос мог выбирать свой стек, запускайте сервер без собственного URL Storage API.
• KBC_KUBERNETES_TOKEN_PATH (только для развёрнутых серверов, см. docs/kubernetes-sa-auth.md): считывается только из среды, никогда — из заголовка.
• KBC_WORKSPACE_ID / KBC_WORKSPACE_SCHEMA: работает так же, как URL Storage API выше: сервер, запущенный с собственной привязкой к рабочей области (через любую из переменных или --workspace-id), сохраняет её для всех запросов; заголовок X-Workspace-Id или X-Workspace-Schema, запрашивающий другую рабочую область, игнорируется (в журнал записывается предупреждение). Сервер без собственной привязки (общий вариант для нескольких пользователей) продолжает получать привязку из каждого запроса, как описано ниже.

Вход в систему

Войдите один раз через браузер; сервер сохранит сеанс и будет автоматически обновлять его, поэтому управлять токенами не придётся:

uvx keboola_mcp_server login --api-url https://connection.YOUR_REGION.keboola.com

Откроется браузер для входа в Keboola, после чего сеанс для всего стека будет сохранён в ~/.keboola/mcp/credentials.json (доступен только вам, по одной записи на стек). Затем запустите сервер, задав только KBC_STORAGE_API_URL — токен не требуется. Выбор проекта или проектов для работы выполняется позже, в ходе диалога (get_accessible_projects / set_project_scope), а не во время входа.

Команда	Назначение
login --api-url <url>	Войти в стек
login --force	Войти снова / сменить учётную запись
login --show-token	Вывести текущий токен сеанса (для отладки)
logout [--api-url <url>] [--all]	Удалить сохранённый сеанс для стека (или для всех стеков)

Если запустить сервер через stdio в интерактивном терминале без сохранённого сеанса, при первом запуске он автоматически выполнит вход через браузер. MCP-клиенты (Claude, Cursor, …) запускают сервер в фоновом режиме, где браузер открыть нельзя, поэтому сначала самостоятельно выполните login.

Запуск без учётной записи Keboola

Сервер также можно запустить, указав только KBC_STORAGE_API_URL и не предоставляя никаких учётных данных. Он запустится в режиме начальной настройки: инструменты, которым нужен доступ к Keboola, объяснят, как получить учётные данные, а один инструмент будет работать без них — create_project. Он создаёт новый проект Keboola, выполняет вход в сеанс и возвращает URL подтверждения. Если открыть этот URL в браузере и войти в систему, проект навсегда станет вашим; до этого момента он временный, и Keboola может его отозвать. После подтверждения созданный инструментом сеанс будет отозван, и вы продолжите работу со своим login.

Для этого нужен стек с включённым предоставлением ресурсов агентам; в остальных случаях инструмент сообщает, что он недоступен.

То же самое можно сделать, не запуская сервер, — на удалённо размещённом MCP-сервере, оператор которого включил эту возможность (KBC_ALLOW_ANONYMOUS_PROVISIONING): такое развёртывание также предоставляет https://mcp.<stack>/mcp-anonymous, который не требует учётных данных. Укажите его в клиенте без аутентификации, вызовите create_project и продолжайте работу в созданном этим вызовом проекте: сервер хранит учётные данные за вас, а инструмент возвращает непрозрачный scope_token, который нужно передавать в последующих вызовах. Для этого используется отдельный URL, поскольку обычная конечная точка /mcp должна и дальше отклонять неаутентифицированные запросы: именно благодаря этому отказу MCP-клиенты понимают, что нужно начать вход через OAuth. Получив проект в своё владение, переключитесь на /mcp и войдите с учётной записью, которой теперь принадлежит проект.

Аутентификация без браузера

Для контейнеров или CI, где вход через браузер невозможен, укажите токен Keboola доступа или персональный токен доступа напрямую: задайте KBC_STORAGE_TOKEN (переменную среды) или отправьте заголовок X-StorageAPI-Token, а также укажите KBC_PROJECT_ID (или заголовок X-KBC-ProjectId), чтобы выбрать проект. При использовании HTTP-транспорта их можно передавать в заголовках каждого запроса, чтобы каждый запрос содержал собственные учётные данные.

KBC_WORKSPACE_ID

Закрепляет запросы за одной конкретной, уже существующей рабочей областью по её ID вместо описанного выше поиска по схеме и имеет приоритет над KBC_WORKSPACE_SCHEMA, если заданы обе переменные. Этот параметр указывает вызывающая сторона Data App / kai-agent в заголовке X-Workspace-Id, чтобы встроенный в приложение Kai выполнял запросы только через собственную рабочую область.

Задайте его с помощью переменной среды KBC_WORKSPACE_ID, флага CLI --workspace-id или заголовка X-Workspace-Id (для каждого запроса в развёртываниях с несколькими пользователями).

KBC_WORKSPACE_SCOPE

strict ограничивает сеанс закреплённой рабочей областью. Это предназначено для Kai в Data App, рабочая область которого использует сопоставление входных данных с прямыми разрешениями. В этом случае сеанс:

• предоставляет только query_data, get_buckets, get_tables, get_project_info и docs_query, независимо от содержимого заголовков авторизации (они могут дополнительно сузить этот список, но не расширить его);
• никогда не ищет и не создаёт рабочую область, управляемую MCP, и не выполняет запросы сразу к нескольким проектам;
• отклоняет рабочую область с доступом только для чтения ко всему Storage, а также отклоняет предварительный просмотр конфигурации. Для этого требуется закрепление рабочей области (KBC_WORKSPACE_ID / X-Workspace-Id). Допустимо только значение strict, поэтому запрос может ужесточить ограничение сеанса, но не ослабить серверное ограничение strict. Задайте его с помощью переменной окружения KBC_WORKSPACE_SCOPE или для отдельного запроса — с помощью заголовка X-Workspace-Scope.

KBC_STORAGE_API_URL (регион Keboola)

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

Регион	URL API
AWS North America	https://connection.keboola.com
AWS Europe	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, задайте ее ID с помощью параметра KBC_BRANCH_ID. MCP-сервер ограничит свою работу указанной веткой, гарантируя, что все изменения останутся изолированными и не затронут рабочую ветку.

• Если параметр не указан, сервер по умолчанию использует рабочую ветку.
• Для разработки задайте KBC_BRANCH_ID числовым ID вашей ветки (например, 123456). ID ветки разработки можно найти в 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.11+
• Доступ к проекту Keboola с правами администратора
• Предпочитаемый MCP-клиент (Claude, Cursor и т. д.)

Примечание: Убедитесь, что у вас установлен uv. MCP-клиент будет использовать его для автоматической загрузки и запуска Keboola MCP Server. Установка 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 Server

Keboola MCP Server можно использовать четырьмя способами — в зависимости от ваших потребностей:

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

В этом режиме Claude или Cursor автоматически запускает MCP-сервер.

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

   uvx keboola_mcp_server login --api-url https://connection.YOUR_REGION.keboola.com
   

2. Настройте MCP-клиент (Claude/Cursor), используя приведенные ниже параметры — требуется только KBC_STORAGE_API_URL.
3. Клиент будет автоматически запускать MCP-сервер по мере необходимости.

Настройка Claude Desktop

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

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

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

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

Настройка Cursor

1. Откройте Settings → MCP
2. Нажмите «+ Add new global MCP Server»
3. Укажите следующие параметры:

{
  "mcpServers": {
    "keboola": {
      "command": "uvx",
      "args": ["keboola_mcp_server --transport <transport>"],
      "env": {
        "KBC_STORAGE_API_URL": "https://connection.YOUR_REGION.keboola.com",
        "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_BRANCH_ID=your_branch_id_optional &&",
          "/snap/bin/uvx keboola_mcp_server --transport <transport>",
          "'"
      ]
    }
  }
}

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

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

1. Клонируйте репозиторий и настройте локальное окружение
2. Настройте 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_BRANCH_ID": "your_branch_id_optional"
      }
    }
  }
}

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

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

# Sign in once (stores a session under ~/.keboola/mcp), then start the server.
export KBC_STORAGE_API_URL=https://connection.YOUR_REGION.keboola.com
uvx keboola_mcp_server login --api-url "$KBC_STORAGE_API_URL"

uvx keboola_mcp_server --transport streamable-http

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

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

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

Контейнер не может открыть браузер, поэтому выполните аутентификацию с помощью токена (см. раздел Аутентификация без браузера): задайте KBC_STORAGE_TOKEN равным токену доступа Keboola или персональному токену доступа, а KBC_PROJECT_ID — целевому проекту. (При работе по HTTP вместо этого можно передавать заголовки X-StorageAPI-Token / X-KBC-ProjectId для каждого запроса и не задавать эти переменные.)

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_TOKEN" \
  -e KBC_PROJECT_ID="YOUR_PROJECT_ID" \
  -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 Server

После настройки и запуска 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

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

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

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

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

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

Проблема	Решение
Ошибки аутентификации	Повторно выполните keboola_mcp_server login (или, если вы проходите аутентификацию с помощью токена, проверьте токен и KBC_PROJECT_ID)
Тайм-аут подключения	Проверьте подключение к сети

Разработка

Установка

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

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, если вы добавили или удалили зависимости. При подготовке релиза также рассмотрите возможность обновить версии зависимостей в файле блокировки (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 запускается только для тегов vX.Y.Z рабочей среды (не для agent-vX.Y.Z и не для предварительных релизов -dev.). Используйте навык release-notes — он подготовит примечания к релизу и черновик PR, а также проведет вас через процесс создания тегов для vX.Y.Z и agent-vX.Y.Z.

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

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

Команда разработки активно отслеживает issues и ответит как можно скорее. Общую информацию о Keboola можно найти в ресурсах ниже.

Ресурсы

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

Связаться с нами

• LinkedIn
• Twitter
• Журнал изменений