karte-datahub-mcp
Allows for querying and analyzing KARTE event data stored in Google BigQuery, offering tools to retrieve events, count records, inspect table schemas, and execute custom SQL queries with built-in security guardrails.
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type
@followed by the MCP server name and your instructions, e.g., "@karte-datahub-mcp show me the schema for KARTE event data"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
karte-datahub-mcp
KARTE のイベントデータを BigQuery 経由で安全にクエリするための MCP(Model Context Protocol)サーバーです。
Claude Code などの MCP 対応 AI アシスタントに KARTE イベントデータへのアクセス機能を提供します。
前提条件
Python 3.13 以上
uv パッケージマネージャー
GCP サービスアカウントの認証情報ファイル
KARTE API キー
Related MCP server: bigquery-mcp
セットアップ
1. 依存関係のインストール
cd karte-datahub-mcp
uv sync2. 環境変数
環境変数 | 必須 | 説明 | デフォルト |
| Yes | KARTE API キー | - |
| No | サービスアカウントキーファイルパス | - |
| No | BigQuery クエリ実行用 GCP プロジェクト | - |
| No | KARTE データプロジェクト |
|
3. Claude Code への登録
.mcp.json に以下を追加します。
{
"mcpServers": {
"karte-datahub-mcp": {
"command": "uv",
"args": ["run", "--directory", "/path/to/karte-datahub-mcp", "karte-mcp-server"],
"env": {
"KARTE_API_KEY": "<your-karte-api-key>",
"CREDENTIAL_FILE": "/path/to/credential.json",
"BQ_PROJECT": "<your-gcp-project>"
}
}
}
}注意
Pathは絶対パスである必要があります
払い出しサービスアカウントを利用する場合は、「BQ_PROJECT」に以下を設定
prd-karte-service-account-2
提供ツール
MCP サーバーとして以下の 4 つのツールを公開します。
query_karte_events - イベントデータ取得
KARTE イベントテーブルからデータを取得します。
パラメータ | 型 | デフォルト | 説明 |
| string |
| SELECT句(例: |
| string | null | null | WHERE条件(例: |
| string | null | 2日前 | 開始日(YYYYMMDD形式) |
| string | null | 昨日 | 終了日(YYYYMMDD形式) |
| int | null | 100 | 取得件数上限(1〜10000)。null で制限なし |
| string | null | null | ORDER BY句(例: |
count_karte_events - イベント件数集計
イベントの件数を集計します。GROUP BY にも対応しています。
パラメータ | 型 | デフォルト | 説明 |
| string | null | null | WHERE条件 |
| string | null | 2日前 | 開始日(YYYYMMDD形式) |
| string | null | 昨日 | 終了日(YYYYMMDD形式) |
| string | null | null | GROUP BY句(例: |
describe_karte_events_schema - スキーマ取得
KARTE イベントテーブルのカラム名・型・説明などのスキーマ情報を返します。パラメータはありません。
execute_karte_sql - カスタムSQL実行
任意の SQL を実行します。ガードレールが自動適用されます。
パラメータ | 型 | デフォルト | 説明 |
| string | - | 実行する SQL 文 |
| bool | false | true でスキャン量のみ確認 |
| bool | false | true で自動 LIMIT 付与をスキップ |
使い方の例
Claude Code から自然言語で利用できます。
> KARTEの直近のイベントを10件見せて
→ query_karte_events(limit=10)
> クリックイベントだけを取得して
→ query_karte_events(where_clause="event_name = 'click'")
> event_name ごとのイベント数を集計して
→ count_karte_events(group_by="event_name")
> テーブルにどんなカラムがあるか教えて
→ describe_karte_events_schema()
> ユーザーごとのイベント数TOP10を出して
→ execute_karte_sql(sql="SELECT user_id, COUNT(*) as cnt FROM ... GROUP BY user_id ORDER BY cnt DESC LIMIT 10")セキュリティ・ガードレール
機能 | 説明 |
破壊的SQL拒否 | DROP, DELETE, INSERT, UPDATE, TRUNCATE, ALTER, CREATE を禁止 |
日付範囲制限 | 最大 30 日間まで |
LIMIT 強制 | カスタム SQL で未指定時に |
| ワイルドカードテーブルへのクエリに日付制約を強制 |
LIMIT 上限 | 1〜10000 の範囲に制限 |
サーバー単体起動
KARTE_API_KEY=<your-key> uv run karte-mcp-serverCloud Run へのデプロイ
Cloud Run にデプロイすると、リモートの MCP サーバーとして複数のクライアントから利用できます。
1. server.py に HTTP トランスポートを追加
現在のサーバーは stdio トランスポートのみ対応しています。Cloud Run で使うには streamable-http トランスポートを追加します。
server.py の main() 関数を以下のように変更します。
import os
def main():
"""MCPサーバーを起動する."""
transport = os.environ.get("MCP_TRANSPORT", "stdio")
if transport == "streamable-http":
_server.run(
transport="streamable-http",
host="0.0.0.0",
port=int(os.environ.get("PORT", "8080")),
)
else:
_server.run(transport="stdio")2. Dockerfile を作成
プロジェクトルート(karte-datahub-mcp/)に Dockerfile を作成します。
FROM python:3.13-slim
COPY --from=ghcr.io/astral-sh/uv:latest /uv /uvx /bin/
WORKDIR /app
COPY pyproject.toml uv.lock ./
RUN uv sync --frozen --no-dev
COPY src/ src/
ENV MCP_TRANSPORT=streamable-http
ENV PORT=8080
EXPOSE 8080
CMD ["uv", "run", "karte-mcp-server"]3. デプロイ
# GCPプロジェクトの設定
export GCP_PROJECT=<your-gcp-project>
export REGION=asia-northeast1
# Cloud Run にデプロイ(ソースから直接ビルド)
gcloud run deploy karte-mcp-server \
--source . \
--project $GCP_PROJECT \
--region $REGION \
--set-env-vars "KARTE_API_KEY=<your-karte-api-key>,MCP_TRANSPORT=streamable-http,BQ_PROJECT=<your-bq-project>" \
--no-allow-unauthenticatedサービスアカウントの認証情報は Cloud Run のデフォルトサービスアカウント、または --service-account で指定したサービスアカウントの権限が使われるため、CREDENTIAL_FILE の設定は不要です。対象の BigQuery データセットへの読み取り権限をサービスアカウントに付与してください。
4. Claude Code からリモートサーバーに接続
デプロイ後、.mcp.json にリモートサーバーとして登録します。
{
"mcpServers": {
"karte-bigquery": {
"type": "streamable-http",
"url": "https://<your-service-url>/mcp/",
"headers": {
"Authorization": "Bearer <id-token>"
}
}
}
}--no-allow-unauthenticated でデプロイした場合、認証トークンが必要です。以下で取得できます。
gcloud auth print-identity-tokenまたは、認証付きプロキシ経由で接続する場合は gcloud run services proxy を利用します。
gcloud run services proxy karte-mcp-server \
--project $GCP_PROJECT \
--region $REGION \
--port 8080この場合、.mcp.json の URL は http://localhost:8080/mcp/ を指定します。
テスト
uv run pytest技術スタック
FastMCP - MCP サーバーフレームワーク
google-cloud-bigquery - BigQuery SDK
Pydantic - データバリデーション
pytest / pytest-asyncio - テスト
Available Tools
4 toolscount_karte_eventsB
KARTEイベントの件数を取得する。
Args: where_clause: WHERE条件(例: "event_name = 'purchase'") date_from: 開始日 YYYYMMDD形式(デフォルト: 2日前) date_to: 終了日 YYYYMMDD形式(デフォルト: 昨日) group_by: GROUP BY句(例: "event_name")
Inputs: where_clause, date_from, date_to, group_by. Returns: result
describe_karte_events_schemaA
KARTEイベントテーブルのスキーマを取得する。
テーブルのカラム名、型、説明等のメタデータを返す。
Inputs: no named parameters. Returns: result
execute_karte_sqlA
カスタムSQLを実行する(ガードレール付き)。
krt_pockyevent_v1_* テーブルへのクエリには _TABLE_SUFFIX 制約が必須。 LIMIT未指定時は自動で LIMIT 1000 が付与される。 破壊的SQL(DROP, DELETE等)は拒否される。
Args: sql: 実行するSQL文 dry_run: Trueの場合、スキャン量のみ確認する no_limit: Trueの場合、自動LIMIT付与をスキップする
Inputs: sql (required), dry_run, no_limit. Returns: result
query_karte_eventsA
KARTEイベントデータを取得する。
日付制約は自動的に適用される(デフォルト: 2日前〜昨日)。
Args: select_columns: SELECT句(デフォルト: "*") where_clause: 追加WHERE条件(例: "event_name = 'click'") date_from: 開始日 YYYYMMDD形式(デフォルト: 2日前) date_to: 終了日 YYYYMMDD形式(デフォルト: 昨日) limit: 取得件数上限 1〜10000(デフォルト: 100)。Noneで制限なし order_by: ORDER BY句(例: "sync_date DESC")
Inputs: select_columns, where_clause, date_from, date_to, +2 more. Returns: result
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
TDQS
Scored across 4 tools
The tools are mostly distinct: count_karte_events counts events, describe_karte_events_schema provides metadata, execute_karte_sql runs custom SQL, and query_karte_events retrieves event data. However, query_karte_events and execute_karte_sql could be confused as both retrieve data, though execute_karte_sql is more flexible with custom SQL while query_karte_events has structured parameters. The descriptions help clarify their boundaries.
All tool names follow a consistent verb_noun pattern with snake_case: count_karte_events, describe_karte_events_schema, execute_karte_sql, and query_karte_events. The naming is predictable and readable throughout the set.
With 4 tools, the count is reasonable for a data query server focused on KARTE events. It covers core operations like counting, describing schema, querying, and custom SQL execution. It might benefit from additional tools for more advanced analytics or data manipulation, but the scope is well-defined and manageable.
The toolset covers basic read operations for KARTE event data, including counting, schema description, structured querying, and custom SQL. However, there are notable gaps: no tools for writing or updating data (e.g., inserting or modifying events), and limited to event data without broader data management capabilities. Agents can work around this for query tasks but may fail for data manipulation needs.
Maintenance
Related MCP Connectors
Query BigQuery, Snowflake, Redshift & Azure Synapse with natural language
Query your Logspot analytics, companies, and revenue from any AI assistant, and run your actions.
Query your app's logs, metrics and incidents from your AI assistant.
Query your Betterlytics web analytics from AI agents: traffic, funnels, journeys, errors, uptime.
Related MCP Servers
- AlicenseBqualityDmaintenanceEnables AI agents to interact with Google BigQuery databases through natural language queries and schema exploration.310MIT
- AlicenseNot gradedqualityDmaintenanceEnables AI assistants to query and analyze Google BigQuery data, including schema browsing, running queries, and comparing datasets through natural language.MIT
- FlicenseNot gradedqualityAmaintenanceEnables LLMs to inspect BigQuery schemas, list tables, describe table structures, and execute SQL queries.-
- FlicenseNot gradedqualityAmaintenanceEnables LLMs to inspect database schemas, list and describe tables, and execute SQL queries against BigQuery using BigQuery dialect.-