karte-datahub-mcp

KARTE のイベントデータを BigQuery 経由で安全にクエリするための MCP（Model Context Protocol）サーバーです。

Claude Code などの MCP 対応 AI アシスタントに KARTE イベントデータへのアクセス機能を提供します。

前提条件

• Python 3.13 以上
• uv パッケージマネージャー
• GCP サービスアカウントの認証情報ファイル
• KARTE API キー

セットアップ

1. 依存関係のインストール

cd karte-datahub-mcp
uv sync

2. 環境変数

環境変数	必須	説明	デフォルト
KARTE_API_KEY	Yes	KARTE API キー	-
CREDENTIAL_FILE	No	サービスアカウントキーファイルパス	-
BQ_PROJECT	No	BigQuery クエリ実行用 GCP プロジェクト	-
DATA_PROJECT	No	KARTE データプロジェクト	karte-data

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 イベントテーブルからデータを取得します。

パラメータ	型	デフォルト	説明
select_columns	string	"*"	SELECT句（例: "event_name, user_id"）
where_clause	string | null	null	WHERE条件（例: "event_name = 'click'"）
date_from	string | null	2日前	開始日（YYYYMMDD形式）
date_to	string | null	昨日	終了日（YYYYMMDD形式）
limit	int | null	100	取得件数上限（1〜10000）。null で制限なし
order_by	string | null	null	ORDER BY句（例: "sync_date DESC"）

count_karte_events - イベント件数集計

イベントの件数を集計します。GROUP BY にも対応しています。

パラメータ	型	デフォルト	説明
where_clause	string | null	null	WHERE条件
date_from	string | null	2日前	開始日（YYYYMMDD形式）
date_to	string | null	昨日	終了日（YYYYMMDD形式）
group_by	string | null	null	GROUP BY句（例: "event_name"）

describe_karte_events_schema - スキーマ取得

KARTE イベントテーブルのカラム名・型・説明などのスキーマ情報を返します。パラメータはありません。

execute_karte_sql - カスタムSQL実行

任意の SQL を実行します。ガードレールが自動適用されます。

パラメータ	型	デフォルト	説明
sql	string	-	実行する SQL 文
dry_run	bool	false	true でスキャン量のみ確認
no_limit	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 1000 を自動付与（no_limit=true でスキップ可）
_TABLE_SUFFIX 必須	ワイルドカードテーブルへのクエリに日付制約を強制
LIMIT 上限	1〜10000 の範囲に制限

サーバー単体起動

KARTE_API_KEY=<your-key> uv run karte-mcp-server

Cloud 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 - テスト