Keboola

公式

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

Keboola MCPで何ができますか？

クエリストレージテーブル — アシスタントにテーブルを直接クエリさせたり、Keboolaプロジェクト内のテーブルやバケットの説明を管理させたりできます。
SQL変換を作成 — 変換内容を自然言語で説明すると、アシスタントがSQL変換を作成します。
ジョブを実行・確認 — コンポーネントや変換のジョブを開始し、実行の詳細を取得します。
コンポーネントとフローを管理 — エクストラクター、ライター、データアプリ、変換設定を作成、一覧表示、確認し、ワークフローパイプラインを構築します。
プロジェクトのメタデータを検索 — 自然言語を使って、プロジェクトのドキュメントやオブジェクトのメタデータを検索、読み取り、更新します。
開発ブランチで作業 — すべての操作を選択した開発ブランチに限定し、変更が本番環境に反映されないようにします。

ドキュメント

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 Agent と MCP Server を使うと、次のことができます。

ストレージ: テーブルを直接クエリし、テーブルやバケットの説明を管理する
コンポーネント: エクストラクター、ライター、データアプリ、変換設定を作成、一覧表示、確認する
SQL: 自然言語で SQL 変換を作成する
ジョブ: コンポーネントや変換を実行し、ジョブ実行の詳細を取得する
フロー: Conditional Flows と Orchestrator Flows を使ってワークフローパイプラインを構築、管理する。
データアプリ: ストレージデータに対するクエリを表示する Keboola Data Apps を作成、デプロイ、管理する — Keboola 管理のリポジトリまたは顧客の GitHub リポジトリ（組織の GitHub 接続を通じてクローンされ、認証情報は保存されません）上の python-js アプリ、および Streamlit アプリ。
メタデータ: 自然言語を使って、プロジェクトのドキュメントやオブジェクトのメタデータを検索、読み取り、更新する
開発ブランチ: 選択したブランチにすべての操作を限定し、本番環境以外の開発ブランチで安全に作業する。

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

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

Remote MCP Server とは？

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

接続方法

リモートサーバーの URL を取得する: Keboola のプロジェクト設定 → MCP Server タブに移動します
サーバー URL をコピーする: 次のような形式です https://mcp.<YOUR_REGION>.keboola.com/mcp
AI アシスタントを設定する: URL を AI アシスタントの MCP 設定に貼り付けます
認証する: Keboola アカウントでのログインを求められます。作業対象のプロジェクトは、その後、会話の中で選択します（例: 「自分の Keboola プロジェクトを一覧表示して」/「プロジェクト X を使って」）

対応クライアント

Cursor: プロジェクトの MCP Server 設定にある「Install In Cursor」ボタンを使うか、次のボタンをクリックします
Claude Desktop: Settings → Integrations から統合を追加します
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`

使用方法:

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

認証:

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

Keboola アカウントでログインする
接続を承認する

認証後、Claude Code から Keboola ツールを直接使用できます。プロジェクトはその後、会話の中で選択します。Claude に使用する Keboola プロジェクトを尋ねるだけです。

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

開発ブランチの使用

本番データに影響を与えずに、Keboola の開発ブランチで安全に作業できます。リモートでホストされる MCP Server は KBC_BRANCH_ID パラメーターを認識し、すべての操作を指定されたブランチに限定します。UI で開発ブランチに移動すると、URL で開発ブランチ ID を確認できます。例: https://connection.us-east4.gcp.keboola.com/admin/projects/PROJECT_ID/branch/BRANCH_ID/dashboard。ブランチ ID は、ヘッダー X-Branch-Id: <branchId> を使って各リクエストに含める必要があります。含めない場合、MCP Server はデフォルトで本番ブランチを使用します。これは、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

ツールの遅延読み込み

ヘッダー	説明	例
`X-Deferred-Tools`	`_meta["anthropic/alwaysLoad"] = false` で一覧表示するツールをカンマ区切りで指定	`run_sync_action,get_flow_schema`

alwaysLoad: true を使ってサーバーを登録する Claude Code / Claude Agent SDK クライアントでは、これらのツールは定義を最初に読み込まず、ツール検索を通じて遅延読み込みされます。このヘッダーが変更するのは tools/list メタデータのみです。ツールを非表示にしたり、認可したりするものではありません。ヘッダーが空の場合、またはツール名が不明な場合は、変更されません。

詳細については、developers.keboola.com/integrate/mcp/#tool-authorization-and-access-control を参照してください。

行レベルおよび列レベルのセキュリティ

行レベルおよび列レベルのポリシーは Keboola Metastore オブジェクト（rls-policy、cls-policy）であり、 kbagent rls / kbagent cls を使って作成します。このサーバーはポリシーを読み取らず、適用もしません。 row-level-security 機能が有効なプロジェクトでは、このサーバーは Connection のログインタイプ governed を使ってワークスペース（keboola.mcp-server-tool コンポーネントの mcp-workspace-<hex> 設定）を作成します。ガバナンス対象のワークスペースには認証情報がありません。読み取りできるのは Query Service のみで、Query Service はすべての query_data 結果をプロジェクトのポリシーに基づいてフィルタリングします。このサーバーによる書き換えやフォールバックはありません。Query Service が拒否した内容は、query_data がエラーとして返します。

有効化の条件。 プロジェクト機能を確認するのはこのサーバーのみです。Connection でガバナンス対象ワークスペースを作成するために、機能やロールは必要ありません（Snowflake または BigQuery、公開鍵は不要）。スタックの Connection は、プロジェクトのバックエンドに対してログインタイプ governed を受け入れる必要があります。受け入れないスタックでは作成が拒否され、その後、ワークスペースを必要とするすべてのツールが失敗します（通常のワークスペースへのフォールバックはありません）。以前に作成した通常の MCP ワークスペースは削除されませんが、機能が有効になると使用されなくなります。機能が有効な場合、workspace_schema または X-Workspace-Id の指定が受け入れられるのは、ガバナンス対象ワークスペースに限られます（通常のワークスペースではポリシーを迂回して読み取れてしまうためです）。そのため、古いワークスペースやデータアプリ独自の通常のワークスペースを指定すると拒否されます。古いワークスペースは削除してください。
デフォルトで拒否。 Query Service は、適用される rls-policy がないガバナンス対象ワークスペースのテーブルを拒否します（"*" ルールは、識別されたすべての読み取りユーザーにテーブルを公開します）。cls-policy だけでは行へのアクセスは許可されません。テーブルを読み取らないステートメント（SELECT 1）は実行されます。拒否はエージェントに Row-level security does not allow this query として返されます。
読み取りユーザーの特定。 Query Service は、プロジェクト管理者自身のトークンから読み取りユーザーを特定します。このサーバーが転送するプログラム用トークン（kbc_at_ / kbc_pat_。マルチプロジェクトスコープの子 PAT を含み、X-KBC-ProjectId とともに送信）または管理者自身のマスター Storage トークンが該当します。それ以外のトークン（統合、データアプリ、Kai）はエンドユーザーを特定せず、検証済みの ID を持たないため、ガバナンス対象テーブルから何も読み取れません。ID にグループが含まれないため、グループルールは一致しません。
バインディング。 バインディングがない場合、ワークスペースにはプロジェクトのすべてのポリシーが適用されます。このサーバーがバインディングを作成することはありません。ワークスペースに一部のポリシーのみを適用するには、KID にバインドします: KID:<stack id>:project-<project id>:workspace-<workspace id>（デフォルトブランチのワークスペースの場合。ブランチのワークスペースでは branch-<branch id> も project より前に指定します）。スタック ID は Query Service の設定に使われているもの（QUERY_RLS_STACK_ID、例: dev-keboola-aws-eu-west-1）です。ワークスペース ID は get_project_info の出力にあり、kbagent rls bind --project P --workspace-id WS --rls-policy ID --stack-id S がバインディングを書き込みます。バインディングは適用範囲を狭めるだけで、次のクエリから適用されます。また、セッションが別のワークスペースに移っても引き継がれません。ブランチセッションや再作成されたワークスペースでは KID が新しくなり、すべてのポリシーが再び適用されます。
制限事項。 サーバーのワークスペース ID は、データアプリ用に別のワークスペースがプロビジョニングされていない場合、データアプリが WORKSPACE_ID として取得する ID でもあります。アプリは独自のトークンでクエリを実行し、検証済みの ID を持たないため、ガバナンス対象テーブルから何も読み取れません。
メタデータ。 メタデータツールに表示されるのは、Query Service が読み取りを許可する情報のみです。get_tables と search（この場合、件数に非表示のテーブルが含まれるため、グローバル検索は使用されません）では、読み取りが許可されていないテーブルは除外されます。ID で指定されたテーブルが読み取り不可の場合、get_tables は見つからないと報告します。列ポリシーが適用されたテーブルでは、ポリシーで許可された列のみが表示されます（主キーおよび search の照合対象にも適用されます）。読み取り可能なテーブルでも、行ポリシーで非表示になる行数とサイズは表示されません。get_buckets ではすべてのバケットが一覧表示されますが、非表示のテーブルを含むテーブル数とサイズは表示されません。これには Query Service エンドポイント POST /api/v1/branches/{branch}/workspaces/{workspace}/rls/scope が必要です。安全側に倒すため、Query Service が判断できない場合、ガバナンス対象プロジェクトのツールは、短いメッセージとテーブルを含まないエラーを返します。この機能が有効でないプロジェクトには影響せず、追加の呼び出しも行いません。

ローカル MCP Server のセットアップ（カスタムまたは開発向け）

完全な制御と簡単な開発のために、MCP server を自分のマシンで実行します。ツールをカスタマイズしたい場合、ローカルでデバッグしたい場合、またはすばやく反復開発したい場合に適しています。サーバーをインストールして認証し（ブラウザーで一度ログインするだけで、トークンの貼り付けは不要）、起動します。この方法は最大限の柔軟性（カスタムツール、ローカルログ、オフラインでの反復開発）を提供しますが、手動でのセットアップが必要で、更新とシークレットは自分で管理します。サーバーは複数のトランスポートオプションに対応しており、サーバーの起動時に --transport <transport> 引数を指定して選択できます。

stdio - --transport が指定されていない場合のデフォルトです。標準入出力を使用し、通常は単一クライアントでのローカルデプロイに使われます。
streamable-http - 双方向ストリーミングチャネルを使用して、HTTP 経由でサーバーをリモート実行します。クライアントとサーバーはメッセージを継続的に交換できます。/mcp 経由で接続します（例: http://localhost:8000/mcp）。
http-compat - streamable-http の別名で、後方互換性のために維持されています。

Keboola プロジェクトで作業するには、サーバーに Keboola Region (KBC_STORAGE_API_URL) と認証手段が必要です。推奨される方法は、ブラウザーで一度だけログインすることです。トークンを作成、コピー、貼り付ける必要はありません。開発ブランチ内で作業する場合は、任意で KBC_BRANCH_ID を設定します。

一部の変数はリクエストヘッダーから取得されません。

KBC_STORAGE_API_URL: 独自の Storage API URL（--api-url パラメーターまたは KBC_STORAGE_API_URL 環境変数）を指定して起動したサーバーは、その Keboola スタックのみを提供します。別のホストを要求する X-Storage-Api-Url ヘッダーは無視され（警告がログに記録されます）、サーバーはリクエストに対して独自の URL を使用します。リクエストごとにスタックを選択できるようにするには、独自の Storage API URL を指定せずにサーバーを起動してください。
KBC_KUBERNETES_TOKEN_PATH（デプロイ済みサーバーのみ。docs/kubernetes-sa-auth.md を参照）: 環境変数からのみ読み取られ、ヘッダーからは読み取られません。
KBC_WORKSPACE_ID / KBC_WORKSPACE_SCHEMA: 上記の Storage API URL と同様に、独自のワークスペース固定値（いずれかの変数、または --workspace-id 経由）を指定して起動したサーバーは、すべてのリクエストでその固定値を使用します。別のワークスペースを要求する X-Workspace-Id または X-Workspace-Schema ヘッダーは無視され（警告がログに記録されます）。独自の固定値を持たないサーバー（共有マルチユーザー構成）では、以下の説明のとおり、リクエストごとにリクエストから固定値を取得します。

ブラウザーが開き、Keboola にサインインすると、スタック全体で使うセッションが ~/.keboola/mcp/credentials.json に保存されます（自分だけが読み取り可能で、スタックごとに1件）。その後、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 へのアクセスが必要なツールは認証情報の取得方法を説明し、認証情報なしで使えるツールは1つだけです。それが create_project です。このツールは新しい Keboola プロジェクトを作成し、セッションをそのプロジェクトにサインインさせ、確認用 URL を返します。その URL をブラウザーで開いてサインインすると、プロジェクトは恒久的に自分のものになります。それまでは一時的なプロジェクトであり、Keboola に回収される可能性があります。確認が完了すると、ツールが作成したセッションは失効し、自分の login を使って作業を続けます。

この機能には、エージェントのプロビジョニングが有効になっているスタックが必要です。それ以外の環境では、ツールは利用できないことを通知します。

サーバーをまったく実行せずに、リモートホスト型 MCP サーバーでも同じことができます。運用者がこの機能を有効にしている場合（KBC_ALLOW_ANONYMOUS_PROVISIONING）、そのデプロイでは認証情報を必要としない https://mcp.<stack>/mcp-anonymous も提供されます。認証なしでクライアントをそこに接続し、create_project を呼び出して、その呼び出しで作成されたプロジェクトで作業を続けます。サーバーが認証情報を保持し、ツールは後続の呼び出しで再送するための不透明な scope_token を返します。通常の /mcp エンドポイントは未認証リクエストを引き続き拒否する必要があるため、これは別の URL です。この拒否によって、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 環境変数、--workspace-id CLI フラグ、または（マルチユーザーデプロイでリクエストごとに指定する場合）X-Workspace-Id ヘッダーで設定します。

KBC_STORAGE_API_URL（Keboola Region）

Keboola Region の 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.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 を使用する方法は4つあります。

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

このモードでは、Claude または Cursor が MCP サーバーを自動的に起動します。

ターミナルで一度ログインしてセッションを保存します（クライアントはブラウザーを開けないバックグラウンドでサーバーを起動します）。
```
uvx keboola_mcp_server login --api-url https://connection.YOUR_REGION.keboola.com
```
以下の設定を使って MCP クライアント（Claude/Cursor）を構成します。必要なのは KBC_STORAGE_API_URL のみです。
必要に応じて、クライアントが MCP サーバーを自動的に起動します。

Claude Desktop の設定

Claude（画面左上）→ Settings → Developer → Edit Config に移動します（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_BRANCH_ID": "your_branch_id_optional"
      }
    }
  }
}

設定ファイルの場所:

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

Cursor の設定

Settings → MCP に移動します。
「+ Add new global MCP Server」をクリックします。
次の設定を行います。

{
  "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 で除外され、Agent に表示されない場合があります。

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_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_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 トランスポートを使用し、/mcp で受信接続を待ち受けます（ポート: localhost:8000）。 --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 トランスポートを使用し、/mcp で受信接続を待ち受けます（ポート: localhost:8000）。 -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を参照してください。

トラブルシューティング

よくある問題

問題	解決策
認証エラー	`keboola_mcp_server login` を再実行します（トークンで認証する場合は、トークンと `KBC_PROJECT_ID` を確認してください）
接続タイムアウト	ネットワーク接続を確認します

開発

インストール

基本セットアップ:

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 ごとにリリースを作成するわけではありません。変更は継続的に trunk（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

Keboola MCPで何ができますか？

ドキュメント

Keboola MCP Server

概要

機能

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

Remote MCP Server とは？

接続方法

対応クライアント

Claude Code のセットアップ

開発ブランチの使用

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

認可ヘッダー

フィルターの動作

読み取り専用ツール

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

ツールの遅延読み込み

行レベルおよび列レベルのセキュリティ

ローカル MCP Server のセットアップ（カスタムまたは開発向け）

ログイン

Keboola アカウントなしで起動する

ブラウザーを使わずに認証する

KBC_WORKSPACE_ID

KBC_STORAGE_API_URL（Keboola Region）

KBC_BRANCH_ID（任意）

インストール

Keboola MCP Server の実行

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

Claude Desktop の設定

Cursor の設定

Windows WSL 向け Cursor の設定

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

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

オプション D: Docker の使用

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

MCP サーバーの使用

セットアップの確認

実行できることの例

互換性

MCP クライアントのサポート

対応ツール

トラブルシューティング

よくある問題

開発

インストール

統合テスト

uv.lock の更新

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

リリース

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

リソース

つながる

`uv.lock` の更新