KARTE Datahub

You can securely query KARTE event data through BigQuery by running a dedicated MCP (Model Context Protocol) server. This server exposes KARTE events to MCP‑compliant AI assistants, enabling you to safely access data for analysis and insights while enforcing security guards and query limits.

How to use

You will connect your MCP client to the karte-datahub-mcp server to run ad‑hoc queries, fetch event data, and obtain schema details. Start the local MCP server or deploy it remotely, then register the remote or local MCP endpoint with your Claude Code instance. From there, you can request event data, count events, retrieve schema information, and execute custom SQL with built‑in safety guards.

How to install

Prerequisites you need before installing include Python 3.13 or newer, the uv package manager, a Google Cloud Platform (GCP) service account credentials file, and a KARTE API key.

# 1. Install dependencies and set up the MCP server project
cd karte-datahub-mcp
uv sync

# 2. Prepare environment variables (example values shown as placeholders)
export KARTE_API_KEY=<your-karte-api-key>
export CREDENTIAL_FILE=/path/to/credential.json
export BQ_PROJECT=<your-gcp-project>
export DATA_PROJECT=karte-data

# 3. Start the MCP server locally (stdio transport)
KARTE_API_KEY=$KARTE_API_KEY uv run karte-mcp-server

Additional sections

Configuration, security, and usage notes help you operate the MCP server confidently. You can configure how to register the server with Claude Code, deploy to Cloud Run, and connect from a remote client. The server provides four tools for interacting with KARTE events: querying events, counting events, describing the event schema, and executing custom SQL with built‑in safety guards.

Key security and guardrails include prohibiting destructive SQL operations, enforcing date range constraints, automatically applying a safe LIMIT when not specified, requiring a table suffix for wildcard table queries, and constraining LIMIT values to a safe range.

You can deploy remotely via Cloud Run and expose a remote MCP endpoint. When deploying, you typically provide environment variables such as your KARTE API key and the BQ project, and you may choose a transport like streamable-http for remote access.

Available tools

query_karte_events

Fetch KARTE events from the KARTE events table with selectable columns, filtering, date range, and result limits.

count_karte_events

Count events with optional grouping by a column, supporting date-range filters.

describe_karte_events_schema

Return the schema information for KARTE events, including columns and data types.

execute_karte_sql

Run arbitrary SQL against the data source with automatic guardrails to prevent unsafe operations.