Сервер Keboola MCP
Сервер Model Context Protocol (MCP) для взаимодействия с Keboola Connection. Этот сервер предоставляет инструменты для листинга и доступа к данным из Keboola Storage API.
Требования
- Python 3.10 или новее
- Токен API хранилища Keboola
- Рабочее пространство Snowflake или BigQuery только для чтения
Установка
Установка через Pip
Сначала создайте виртуальную среду, а затем установите пакет keboola_mcp_server :
python3 -m venv --upgrade-deps .venv
source .venv/bin/activate
pip3 install keboola_mcp_server
Установка через Smithery
Чтобы автоматически установить Keboola MCP Server для Claude Desktop через Smithery :
npx -y @smithery/cli install keboola-mcp-server --client claude
Настройка рабочего стола Клода
Чтобы использовать этот сервер с Claude Desktop, выполните следующие действия:
- Создайте или отредактируйте файл конфигурации Claude Desktop:
- macOS :
~/Library/Application Support/Claude/claude_desktop_config.json - Windows :
%APPDATA%\Claude\claude_desktop_config.json
- Добавьте следующую конфигурацию (измените пути в соответствии с вашими настройками):
{
"mcpServers": {
"keboola": {
"command": "uvx",
"args": [
"keboola_mcp_server",
"--api-url",
"https://connection.YOUR_REGION.keboola.com"
],
"env": {
"KBC_STORAGE_TOKEN": "your_keboola_storage_token",
"KBC_WORKSPACE_SCHEMA": "your_workspace_schema"
}
}
}
}
Заменять:
/path/to/keboola-mcp-server на ваш фактический путь к клонированному репозиториюYOUR_REGION с вашим регионом Keboola (например, north-europe.azure и т.д.). Вы можете удалить его, если ваш регион — это просто connection явноyour_keboola_storage_token с вашим токеном API хранилища Keboolayour_workspace_schema с вашей схемой Snowflake или набором данных BigQuery вашего рабочего пространства
Примечание: Если вы используете определенную версию Python (например, 3.11 из-за проблем совместимости некоторых пакетов), вам необходимо обновить command , указав эту конкретную версию, например /path/to/keboola-mcp-server/.venv/bin/python3.11
Примечание: рабочее пространство можно создать в вашем проекте Keboola. Это тот же проект, в котором вы получили свой Storage Token. Рабочее пространство предоставит все необходимые параметры подключения, включая имя схемы или набора данных.
- После обновления конфигурации:
- Полностью закройте Claude Desktop (не просто закройте окно)
- Перезагрузить рабочий стол Клода
- Найдите значок молотка в правом нижнем углу, указывающий на то, что сервер подключен.
Поиск неисправностей
Если у вас возникли проблемы с подключением:
- Проверьте журналы в Claude Desktop на наличие сообщений об ошибках.
- Проверьте правильность токена API хранилища Keboola.
- Убедитесь, что все пути в конфигурации являются абсолютными.
- Убедитесь, что виртуальная среда правильно активирована и все зависимости установлены.
Настройка курсора AI
Чтобы использовать этот сервер с Cursor AI, у вас есть два варианта настройки метода транспортировки: Server-Sent Events (SSE) или Standard I/O (stdio).
- Создайте или отредактируйте файл конфигурации Cursor AI:
- Расположение:
~/.cursor/mcp.json
- Добавьте одну из следующих конфигураций (или все) в зависимости от предпочитаемого вами способа транспортировки:
Вариант 1: использование событий, отправленных сервером (SSE)
{
"mcpServers": {
"keboola": {
"url": "http://localhost:8000/sse?storage_token=YOUR_KEBOOLA_STORAGE_TOKEN&workspace_schema=YOUR_WORKSPACE_SCHEMA"
}
}
}
Вариант 2а: использование стандартного ввода-вывода (stdio)
{
"mcpServers": {
"keboola": {
"command": "uvx",
"args": [
"keboola_mcp_server",
"--transport",
"stdio",
"--api-url",
"https://connection.YOUR_REGION.keboola.com"
],
"env": {
"KBC_STORAGE_TOKEN": "your_keboola_storage_token",
"KBC_WORKSPACE_SCHEMA": "your_workspace_schema"
}
}
}
}
Вариант 2б: использование стандартного ввода-вывода WSL (wsl stdio)
При запуске сервера MCP из подсистемы Windows для Linux с Cursor AI используйте это.
{
"mcpServers": {
"keboola": {
"command": "wsl.exe",
"args": [
"bash",
"-c",
"'source /wsl_path/to/keboola-mcp-server/.env",
"&&",
"/wsl_path/to/keboola-mcp-server/.venv/bin/python -m keboola_mcp_server.cli --transport stdio'"
]
}
}
}
- где файл
/wsl_path/to/keboola-mcp-server/.env содержит переменные среды:
export KBC_STORAGE_TOKEN="your_keboola_storage_token"
export KBC_WORKSPACE_SCHEMA="your_workspace_schema"
Заменять:
/path/to/keboola-mcp-server на ваш фактический путь к клонированному репозиториюYOUR_REGION с вашим регионом Keboola (например, north-europe.azure и т.д.). Вы можете удалить его, если ваш регион — это просто connection явноyour_keboola_storage_token с вашим токеном API хранилища Keboolayour_workspace_schema с вашей схемой Snowflake или набором данных BigQuery вашего рабочего пространства
После обновления конфигурации:
- Перезапустить курсор AI
- Если вы используете транспорт
sse , убедитесь, что вы запустили свой сервер MCP. Вы можете сделать это, запустив это в активированной виртуальной среде, где вы построили сервер:/path/to/keboola-mcp-server/.venv/bin/python -m keboola_mcp_server --transport sse --api-url https://connection.YOUR_REGION.keboola.com
- Курсор AI должен автоматически обнаружить ваш сервер MCP и включить его.
Поддержка BigQuery
Если ваш проект Keboola использует бэкэнд BigQuery, вам необходимо установить переменную среды GOOGLE_APPLICATION_CREDENTIALS в дополнение к KBC_STORAGE_TOKEN и KBC_WORKSPACE_SCHEMA .
- Перейдите в рабочее пространство Keboola BigQuery и отобразите его учетные данные (нажмите кнопку «
Connect »). - Загрузите файл учетных данных на локальный диск. Это простой файл JSON.
- Задайте полный путь к загруженному файлу учетных данных JSON в переменной среды
GOOGLE_APPLICATION_CREDENTIALS .
Это предоставит вашему экземпляру сервера MCP разрешения на доступ к вашему рабочему пространству BigQuery в Google Cloud.
Доступные инструменты
Сервер предлагает множество инструментов для взаимодействия с Keboola Connection. Подробную документацию по всем доступным инструментам см. на TOOLS.md .
Инструменты для хранения
SQL-инструменты
- get_sql_dialect : получает имя диалекта SQL, используемого базовой базой данных проекта Keboola.
- query_table : выполняет запрос SQL SELECT для получения данных из базовой базы данных.
Инструменты для компонентов
- create_sql_transformation : создает преобразование SQL, используя указанное имя, запрос SQL, следующий за текущим диалектом SQL, подробное описание и, при необходимости, список имен созданных таблиц, если и только если они созданы в операторах SQL.
- get_component_details : получает подробную информацию о конкретной конфигурации компонента Keboola по заданному идентификатору компонента/преобразования и идентификатору конфигурации.
- retrieve_components : извлекает конфигурации компонентов в проекте, при необходимости фильтруя их по типам компонентов или определенным идентификаторам компонентов. Если указаны component_ids, извлекаются только те компоненты, которые идентифицированы этими идентификаторами, без учета component_types.
- retrieve_transformations : извлекает конфигурации преобразований в проекте, при необходимости фильтруя их по определенным идентификаторам преобразований.
Работа Инструменты
- get_job_detail : получает подробную информацию о конкретной работе, идентифицированной по job_id, включая ее статус, параметры, результаты и любые соответствующие метаданные.
- retrieve_jobs : извлекает все задания в проекте или фильтрует задания по определенному component_id или config_id с дополнительной фильтрацией по статусу.
- start_job : запускает новую задачу для указанного компонента или преобразования.
Инструменты для документирования
- docs_query : отвечает на вопрос, используя документацию Keboola в качестве источника.
Разработка
Проведите тесты:
Формат кода:
Проверка типа:
Лицензия
Лицензия MIT — подробности см. в файле LICENSE.