Skip to main content
Glama
YusukeYajima

karte-datahub-mcp

by YusukeYajima
OverviewSchemaRelated ServersScoreDiscussions
Python
Hybrid

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

Install Server
A
security – no known vulnerabilities
F
license - not found
A
quality - confirmed to work

How are these scores calculated?

Resources

Unclaimed servers have limited discoverability.

Looking for Admin?

If you are the server author, to access and configure the admin panel.

Tools

Latest Blog Posts

MCP directory API

We provide all the information about MCP servers via our MCP API.

curl -X GET 'https://glama.ai/api/mcp/v1/servers/YusukeYajima/karte-datahub-mcp'

If you have feedback or need assistance with the MCP directory API, please join our Discord server