Keboola MCP Server

公式

単一の直感的なプラットフォーム上で、堅牢なデータワークフロー、統合、分析を構築できます。

ドキュメント

Keboola MCP Server

AIエージェント、MCPクライアント（Cursor、Claude、Windsurf、VS Codeなど）、その他のAIアシスタントをKeboolaに接続します。データ、変換、SQLクエリ、ジョブトリガーを公開し、グルーコードは不要です。エージェントが必要な時に、必要な場所で、適切なデータを提供します。

概要

Keboola MCP Serverは、Keboolaプロジェクトと最新のAIツールを繋ぐオープンソースのブリッジです。ストレージアクセス、SQL変換、ジョブトリガーなどのKeboolaの機能を、Claude、Cursor、CrewAI、LangChain、Amazon Qなどから呼び出し可能なツールに変えます。

クイックスタート
ローカルセットアップ

機能

AIエージェントとMCPサーバーを使用すると、次のことが可能になります。

ストレージ: テーブルを直接クエリし、テーブルやバケットの説明を管理
コンポーネント: 抽出、書き込み、データアプリ、変換設定の作成、一覧表示、検査
SQL: 自然言語でSQL変換を作成
ジョブ: コンポーネントと変換を実行し、ジョブ実行の詳細を取得
フロー: 条件付きフローとオーケストレーターフローを使用してワークフローパイプラインを構築・管理
データアプリ: ストレージデータに対するクエリを表示するKeboola Streamlitデータアプリを作成、デプロイ、管理
メタデータ: 自然言語を使用してプロジェクトドキュメントとオブジェクトメタデータを検索、読み取り、更新
開発ブランチ: 本番環境外の開発ブランチで安全に作業し、すべての操作は選択したブランチにスコープされます。

🚀 クイックスタート: リモートMCPサーバー（最も簡単な方法）

Keboola MCP Serverを使用する最も簡単な方法は、リモートMCPサーバーを利用することです。このホスト型ソリューションにより、ローカルでのセットアップ、設定、インストールが不要になります。

リモートMCPサーバーとは？

当社のリモートサーバーは、すべてのマルチテナントKeboolaスタックでホストされており、OAuth認証をサポートしています。リモートのStreamable HTTP接続とOAuth認証をサポートする任意のAIアシスタントから接続できます。

接続方法

リモートサーバーのURLを取得: Keboolaプロジェクト設定 → MCP Server タブに移動します
サーバーURLをコピー: https://mcp.<YOUR_REGION>.keboola.com/mcp のような形式です
AIアシスタントを設定: AIアシスタントのMCP設定にURLを貼り付けます
認証: Keboolaアカウントで認証し、プロジェクトを選択するよう求められます

サポートされているクライアント

Cursor: プロジェクトのMCPサーバー設定にある「Cursorにインストール」ボタンを使用するか、このボタンをクリックします
Claude Desktop: 設定 → 統合から統合を追加
Claude Code: claude mcp add --transport http keboola <URL> を使用してインストール（詳細は以下を参照）
Windsurf: リモートサーバーURLで設定
Make: リモートサーバーURLで設定
その他のMCPクライアント: リモートサーバーURLで設定

Claude Codeのセットアップ

Claude Codeは、ターミナルを使用してClaudeと対話できるコマンドラインインターフェースツールです。簡単なコマンドでKeboola MCP Server統合をインストールできます。

インストール:

ターミナルで次のコマンドを実行し、<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`

使用方法:

インストール後、Claude Codeで /mcp と入力し、使用するKeboolaツールを選択することで、Keboola MCP Serverを使用できます。

認証:

Claude Codeで初めてKeboola MCP Serverを使用する際、ブラウザウィンドウが開き、次の操作を求められます。

Keboolaアカウントでログイン
接続するプロジェクトを選択
接続を承認

認証後、Claude Codeから直接Keboolaツールを使用できるようになります。

詳細なセットアップ手順とリージョン固有のURLについては、リモートサーバーセットアップドキュメントを参照してください。

開発ブランチの使用

本番データに影響を与えることなく、Keboola開発ブランチで安全に作業できます。リモートでホストされるMCPサーバーは KBC_BRANCH_ID パラメータを尊重し、すべての操作を指定されたブランチにスコープします。開発ブランチIDは、UIで開発ブランチに移動した際のURLで確認できます（例: https://connection.us-east4.gcp.keboola.com/admin/projects/PROJECT_ID/branch/BRANCH_ID/dashboard）。ブランチIDは、ヘッダー X-Branch-Id: <branchId> を使用して各リクエストに含める必要があります。含めない場合、MCPサーバーはデフォルトで本番ブランチを使用します。これは、AIクライアントまたはサーバー接続を処理する環境で管理する必要があります。

ツールの認可とアクセス制御

HTTPベースのトランスポート（Streamable 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。これらは2つの方法で提供できます。

個人使用（主にstdioトランスポート）: サーバー起動前に環境変数を設定します。すべてのリクエストでこれらの事前定義された認証情報が再利用されます。
マルチユーザー使用: リクエストヘッダーに変数を含め、各リクエストで提供された認証情報が使用されるようにします。

KBC_STORAGE_TOKEN

これはKeboolaの認証トークンです。

ストレージAPIトークンの作成と管理方法については、Keboola公式ドキュメントを参照してください。

注: MCPサーバーに制限付きアクセスを許可する場合はカスタムストレージトークンを使用し、プロジェクト内のすべてにアクセスさせる場合はマスタートークンを使用します。

KBC_WORKSPACE_SCHEMA

これはKeboola内のワークスペースを識別し、SQLクエリに使用されます。ただし、これはマスタートークンの代わりにカスタムストレージトークンを使用している場合にのみ必要です。

マスタートークンを使用する場合: ワークスペースはバックグラウンドで自動的に作成されます
カスタムストレージトークンを使用する場合: このKeboolaガイドに従ってKBC_WORKSPACE_SCHEMAを取得してください

注: ワークスペースを手動で作成する場合は、「すべてのプロジェクトデータへの読み取り専用アクセスを許可する」オプションをチェックしてください

注: KBC_WORKSPACE_SCHEMAは、BigQueryワークスペースではデータセット名と呼ばれます。「接続」をクリックしてデータセット名をコピーするだけです。

KBC_STORAGE_API_URL（Keboolaリージョン）

KeboolaリージョンAPI URLは、デプロイリージョンによって異なります。Keboolaプロジェクトにログインした際のブラウザのURLを確認することで、リージョンを特定できます。

リージョン	API URL
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開発ブランチで操作するには、KBC_BRANCH_ID パラメータを使用してブランチIDを設定します。MCPサーバーはその機能を指定されたブランチにスコープし、すべての変更が分離され、本番ブランチに影響を与えないようにします。

指定しない場合、サーバーはデフォルトで本番ブランチを使用します。
開発作業の場合は、KBC_BRANCH_ID をブランチの数値ID（例: 123456）に設定します。開発ブランチIDは、UIで開発ブランチに移動した際の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 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を使用する4つの方法があります。

オプション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でフィルタリングされ、エージェントに表示されない場合があります。

Windows WSL用のCursor設定

Windows Subsystem for LinuxからCursor AIでMCPサーバーを実行する場合は、次の設定を使用します。

{
  "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サーバーコード自体に取り組む開発者向け:

リポジトリをクローンし、ローカル環境をセットアップします
ローカルのPythonパスを使用するようにClaude/Cursorを設定します:

{
  "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

推奨セットアップでは、テストとコードスタイルチェック用のパッケージがインストールされ、VsCodeやCursorなどのIDEが開発中にコードをチェックしたりテストを実行したりできるようになります。

統合テスト

統合テストをローカルで実行するには、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) に継続的にマージされ、変更がまとめて再テストされた後に定期的にリリースされます。これにより、ユーザーの動作中のセットアップが壊れるのを防ぎます。

リリースは、1つまたは2つのgitタグをプッシュすることで行われます:

vX.Y.Z — MCPサーバーリリース (常に)
agent-vX.Y.Z — In Platform Agentリリース (エージェントもリリースされる場合のみ)

いずれかのタグが release.yml CIをトリガーし、Dockerイメージをビルドして公開します。KaiBenchは本番用の vX.Y.Z タグでのみ実行されます (agent-vX.Y.Z や -dev. プレリリースでは実行されません)。release-notes スキルを使用してください。これはリリースノートとドラフトPRを準備し、vX.Y.Z と agent-vX.Y.Z の両方のタグ付け手順を説明します。

サポートとフィードバック

⭐ ヘルプの取得、バグの報告、機能リクエストの主な方法は、GitHubでIssueを作成することです。⭐

開発チームはIssueを積極的に監視しており、可能な限り迅速に対応します。Keboolaに関する一般的な情報については、以下のリソースをご利用ください。

Keboola MCP Server

ドキュメント

Keboola MCP Server

概要

機能

🚀 クイックスタート: リモートMCPサーバー（最も簡単な方法）

リモートMCPサーバーとは？

接続方法

サポートされているクライアント

Claude Codeのセットアップ

開発ブランチの使用

ツールの認可とアクセス制御

認可ヘッダー

フィルターの動作

読み取り専用ツール

例: 読み取り専用アクセス

ローカルMCPサーバーセットアップ（カスタムまたは開発方法）

KBC_STORAGE_TOKEN

KBC_WORKSPACE_SCHEMA

KBC_STORAGE_API_URL（Keboolaリージョン）

KBC_BRANCH_ID（オプション）

インストール

Keboola MCP Serverの実行

オプションA: 統合モード（推奨）

Claude Desktopの設定

Cursorの設定

Windows WSL用のCursor設定

オプションB: ローカル開発モード

オプションC: 手動CLIモード (テスト専用)

オプションD: Dockerの使用

サーバーを自分で起動する必要がありますか？

MCPサーバーの使用

セットアップの確認

実行可能な操作の例

互換性

MCPクライアントサポート

サポートされているツール

トラブルシューティング

一般的な問題

開発

インストール

統合テスト

uv.lock の更新

ツールドキュメントの更新

リリース

サポートとフィードバック

リソース

接続

`uv.lock` の更新