MCP Hub
Back to servers

karte-datahub-mcp

sampleのMCP

glama
Data & Analytics
Updated
Feb 9, 2026
View Source
Claim this server

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_KEYYesKARTE API キー-
CREDENTIAL_FILENoサービスアカウントキーファイルパス-
BQ_PROJECTNoBigQuery クエリ実行用 GCP プロジェクト-
DATA_PROJECTNoKARTE データプロジェクト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_columnsstring"*"SELECT句（例: "event_name, user_id"）
where_clausestring | nullnullWHERE条件（例: "event_name = 'click'"）
date_fromstring | null2日前開始日（YYYYMMDD形式）
date_tostring | null昨日終了日（YYYYMMDD形式）
limitint | null100取得件数上限（1〜10000）。null で制限なし
order_bystring | nullnullORDER BY句（例: "sync_date DESC"）

count_karte_events - イベント件数集計

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

パラメータ型デフォルト説明
where_clausestring | nullnullWHERE条件
date_fromstring | null2日前開始日（YYYYMMDD形式）
date_tostring | null昨日終了日（YYYYMMDD形式）
group_bystring | nullnullGROUP BY句（例: "event_name"）

describe_karte_events_schema - スキーマ取得

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

execute_karte_sql - カスタムSQL実行

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

パラメータ型デフォルト説明
sqlstring-実行する SQL 文
dry_runboolfalsetrue でスキャン量のみ確認
no_limitboolfalsetrue で自動 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 - テスト

Reviews

No reviews yet

Sign in to write a review