Skip to main content
Glama
mxfksta

Kilkaya MCP Server

by mxfksta
OverviewSchemaSourceRelated ServersScoreDiscussionsAdmin
TypeScript
Remote

Kilkaya MCP Server

Ein MCP-Server (Model Context Protocol) für die Kilkaya-Analytics-API. Er stellt Kilkayas Query-, Schema- und Metadata-Endpunkte als MCP-Tools bereit, läuft über Streamable HTTP (stateless) und ist für das Hosting auf Google Cloud Run ausgelegt.

Tools

Standardmäßig aktiv (read-only):

Tool

Kilkaya-Endpunkt

Beschreibung

kilkaya_query

POST /api/query

Analytics-Query (Haupt-API). Antwort im JSON:API-Format. 202-Antworten („Query queued/running") werden automatisch alle 2,5 s neu gesendet, bis das Ergebnis da ist (Timeout konfigurierbar).

kilkaya_list_schemas

GET /api/schemas

Verfügbare Schemas inkl. Felddefinitionen. allfields ist die verbindliche Liste gültiger Felder, timefields (_minute, _day, _month, …) können als Spalten für Zeitaggregation ergänzt werden.

kilkaya_get_metadata

GET /api/metadata

Metadaten für eine Artikel-URL (ohne Protokoll).

kilkaya_get_metadata_bulk

POST /api/metadata

Metadaten für viele URLs auf einmal.

Optional per Env-Flag:

Tool

Flag

Beschreibung

kilkaya_set_metadata

KILKAYA_ENABLE_WRITE_TOOLS=true

Schreibt/aktualisiert Artikel-Metadaten (POST /api/metadata/set).

kilkaya_list_users, kilkaya_get_user, kilkaya_list_roles, kilkaya_get_role

KILKAYA_ENABLE_ADMIN_TOOLS=true

Read-only User-/Rollen-Verwaltung. Standardmäßig aus, da Userdaten E-Mail-Adressen enthalten.

Destruktive Endpunkte (User/Rollen anlegen, ändern, löschen) sind bewusst nicht als Tools implementiert.

Related MCP server: Seline MCP

Konfiguration (Umgebungsvariablen)

Variable

Pflicht

Beschreibung

KILKAYA_API_TOKEN

✅

Kilkaya API Access Token. Wird als Authorization: Bearer <token> an die API gesendet. In Cloud Run über Secret Manager setzen, nicht als Klartext-Env.

MCP_AUTH_TOKEN

empfohlen

Shared Secret zum Schutz des /mcp-Endpunkts. Clients müssen Authorization: Bearer <token> mitschicken. Ohne diese Variable ist der Endpunkt ungeschützt — dann Cloud Run nicht mit --allow-unauthenticated deployen.

PORT

–

HTTP-Port (Default 8080; wird von Cloud Run automatisch gesetzt).

KILKAYA_BASE_URL

–

Default https://api.kilkaya.com.

KILKAYA_QUERY_TIMEOUT_MS

–

Wie lange auf ein 202-„Query delayed" gepollt wird (Default 90000). Läuft der Timeout ab, liefert das Tool den Queue-Status zurück; derselbe Query kann einfach erneut abgeschickt werden.

KILKAYA_ENABLE_WRITE_TOOLS

–

true aktiviert kilkaya_set_metadata.

KILKAYA_ENABLE_ADMIN_TOOLS

–

true aktiviert die read-only User-/Rollen-Tools.

Lokal starten

npm install
npm run build
KILKAYA_API_TOKEN=<token> npm start
# Healthcheck
curl http://localhost:8080/healthz

MCP-Endpunkt: POST http://localhost:8080/mcp (Streamable HTTP, stateless — keine Sessions, kein SSE-Stream vom Server; GET/DELETE /mcp antworten mit 405).

Deployment auf Google Cloud Run

PROJECT=<gcp-projekt>
REGION=europe-west3

# 1. Token als Secret hinterlegen
echo -n "<kilkaya-api-token>" | gcloud secrets create kilkaya-api-token \
  --project "$PROJECT" --data-file=-
echo -n "<selbst-generiertes-shared-secret>" | gcloud secrets create kilkaya-mcp-auth-token \
  --project "$PROJECT" --data-file=-

# 2. Bauen & deployen (Cloud Build baut das Dockerfile)
gcloud run deploy kilkaya-mcp \
  --project "$PROJECT" --region "$REGION" \
  --source . \
  --set-secrets "KILKAYA_API_TOKEN=kilkaya-api-token:latest,MCP_AUTH_TOKEN=kilkaya-mcp-auth-token:latest" \
  --allow-unauthenticated \
  --min-instances 0 --max-instances 3 --memory 256Mi

--allow-unauthenticated ist hier okay, weil MCP_AUTH_TOKEN den Endpunkt schützt. Alternativ das Flag weglassen und Cloud-Run-IAM nutzen (Clients senden dann ein Google-ID-Token) — dann kann MCP_AUTH_TOKEN entfallen.

Der Server ist stateless (ein frischer MCP-Server pro Request), daher sind beliebige Instanzzahlen inkl. Scale-to-zero unproblematisch.

Client-Konfiguration

Beispiel für Claude Code (.mcp.json) oder andere MCP-Clients mit Streamable HTTP:

{
  "mcpServers": {
    "kilkaya": {
      "type": "http",
      "url": "https://kilkaya-mcp-<hash>-<region>.a.run.app/mcp",
      "headers": {
        "Authorization": "Bearer <selbst-generiertes-shared-secret>"
      }
    }
  }
}

Beispiel-Query

Typischer Ablauf für ein LLM: erst kilkaya_list_schemas aufrufen, um Schema und gültige Felder zu ermitteln, dann kilkaya_query:

{
  "schemaname": "pageviews",
  "datefrom": "2026-07-01T00:00:00+00:00",
  "dateto": "2026-07-06T00:00:00+00:00",
  "columns": ["url", "pageviews", "section", "_day"],
  "filters": [
    { "column": "url", "operator": "like", "value": "*example.de*" }
  ],
  "sortby": ["pageviews"],
  "sortorder": ["desc"],
  "limit": 100
}

Filter-Operatoren: like, notlike, greater, less. Wildcards mit * (nicht %).

Projektstruktur

src/
  index.ts    – Express-App, Streamable-HTTP-Transport, Auth, /healthz
  server.ts   – MCP-Server- und Tool-Definitionen
  kilkaya.ts  – HTTP-Client für die Kilkaya-API inkl. 202-Polling
Dockerfile    – Multi-Stage-Build (Node 22 Alpine)

This server cannot be installed

RayrunBuild, deploy, and operate MCP servers without becoming an infrastructure team.ray.runAd

Maintenance

ActivitySlowing
ResponsivenessNo issues

Resources

Unclaimed servers have limited discoverability.

Looking for Admin?

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

Related MCP Connectors

Related MCP Servers

  • Seline MCP

    getseline
    A
    license
    Not graded
    quality
    C
    maintenance
    MCP server for Seline Analytics API
    74
    2
    MIT

  • WhatsMyBudgetMCP

    joshuarreid
    F
    license
    A
    quality
    D
    maintenance
    MCP server for the WhatsMyBudget Analytics API, providing tools to query budget periods, categories, accounts, and summaries.
    26
    -

  • analytics-mcp

    adtechnacity
    A
    license
    Not graded
    quality
    C
    maintenance
    MCP server for querying Google Analytics accounts, properties, reports, and realtime data using the Data API and Admin API.
    Apache 2.0