Skip to main content
Glama
karte-datahub-mcp

karte-datahub-mcp

by YusukeYajima

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

Available Tools

4 tools
count_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

    A3.8/5.0

    Scored across 4 tools

    Disambiguation4/5

    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.

    Naming Consistency5/5

    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.

    Tool Count4/5

    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.

    Completeness3/5

    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

    ActivityInactive
    ResponsivenessNo recent community issues

    Related MCP Connectors

    Related MCP Servers