Skip to main content
Glama
Framedash Game Telemetry MCP Server

Framedash Game Telemetry MCP Server

by crane-valley

@framedash/mcp-server

MCP (Model Context Protocol) server for the Framedash game telemetry platform. This server provides 14 read-only tools over stdio and 4 resources for querying analytics data from LLM-powered tools. Version 0.2.0 provides 12 tools and does not include the build comparison tools or structured heatmap context.

Setup

Claude Desktop

Add to your claude_desktop_config.json:

{
  "mcpServers": {
    "framedash": {
      "command": "npx",
      "args": ["@framedash/mcp-server"],
      "env": {
        "FRAMEDASH_API_KEY": "fd_xxx",
        "FRAMEDASH_PROJECT_ID": "your-project-uuid"
      }
    }
  }
}

VS Code (Claude Extension)

Add to your VS Code settings:

{
  "claude.mcpServers": {
    "framedash": {
      "command": "npx",
      "args": ["@framedash/mcp-server"],
      "env": {
        "FRAMEDASH_API_KEY": "fd_xxx",
        "FRAMEDASH_PROJECT_ID": "your-project-uuid"
      }
    }
  }
}

Related MCP server: xeve-mcp-server

Environment Variables

Variable

Required

Description

FRAMEDASH_API_KEY

Yes

API key with analytics:read for the aggregate tools; the raw query tool additionally requires data:admin

FRAMEDASH_PROJECT_ID

No

Default project UUID for project-scoped tools

FRAMEDASH_BASE_URL

No

API base URL (default: https://app.framedash.dev)

If FRAMEDASH_PROJECT_ID is omitted, project-scoped tools still work but require an explicit project_id argument per call.

Tools

Tool

Description

query

Execute SQL analytics query (SELECT only, limit default 100)

get_dashboard

Project KPI summary (DAU, MAU, sessions, events)

get_retention

Cohort retention data

get_funnel

Funnel analysis for event steps

get_insights

Event insights with grouping

get_heatmap

Heatmap grid data for a map

list_projects

Show the project bound to the API key

get_project_status

Project health overview

list_maps

List maps in a project

list_content

List content registry entries

list_alerts

List alert rules

get_alert_history

Alert trigger history

list_builds

List builds or find an exact build ID

compare_builds

Compare two builds without applying a CI threshold

Build comparison and heatmap context

When the hosted OAuth endpoint runs this server revision, it exposes 13 tools: query is omitted because OAuth cannot grant data:admin. Hosted availability depends on the deployed server revision.

Tool

Scope

Input / output

list_builds

analytics:read

Optional project_id, days (7/14/30/90; default 30), exact build_id, fresh (default false). Returns the existing builds payload; an exact build avoids the newest-50 list cap.

compare_builds

analytics:read

Required distinct baseline/candidate build IDs; optional project_id, days (7/14/30/90; default 30), map_id, platform, fresh (default false). Returns the existing P50/P95 comparison payload and sample/session counts; does not apply a CI threshold.

get_heatmap context

analytics:read

Legacy text remains unchanged. structuredContent.cells contains the same complete cells as the legacy JSON prefix; total, returned, and truncated describe response truncation. context records filters, world-coordinate units, metric units, and unknown axis/null causes; use list_maps.upAxis to determine X/Z versus X/Y.

Heatmap response truncation is a presentation limit, not ingestion readiness or missing telemetry. Legacy text retains its existing 51,200 UTF-16-unit limit and, on overflow, at most 50 complete cells. Structured cells are recovered from that bounded JSON prefix without serializing the full source array again. If one cell exceeds the text limit and only a partial cell is displayed, structured cells are empty and returned: 0, truncated: true makes that omission explicit. total is the source cell count.

Metadata filter strings (project_id, map_id, event_name) are limited to 256 UTF-16 units. Names in context.truncated_fields identify prefix values; the actual API request uses the full filter. Metadata truncation is separate from cell truncation. Including both text and structured representations, the JSON-encoded tool result stays within 6 * 51,200 + 8,192 = 315,392 bytes: each bounded representation needs at most three UTF-8 bytes per UTF-16 unit, and 8 KiB covers the fixed context, capped filter values and result fields. JSON-RPC envelope IDs are client-controlled and outside this tool-result budget.

compare_builds.isRegression reports direction, not a threshold breach or statistical certainty. Sample/session counts do not verify expected samples or completed ingestion. Map/platform filters change the population; load_time_ms is unavailable with a map filter. Null metric causes remain unknown. The existing CLI framedash perf-diff --threshold <pct> --fail-on-regression provides an opt-in CI gate without requiring raw SQL access.

Resources

URI

Description

framedash://projects

Project bound to the API key

framedash://projects/{projectId}/maps

Map list with bounds

framedash://projects/{projectId}/content

Content registry

framedash://projects/{projectId}/status

Project health status

Hosted HTTP compatibility

The stateless hosted HTTP endpoint /api/mcp rejects request batches containing more than 100 messages with HTTP 400 and JSON-RPC error code -32600. This limit applies per POST request and is separate from the existing 1 MiB request-body limit. The independent stdio transport remains unaffected.

To accommodate this bound, update clients to split message batches into groups of at most 100 messages, or transmit messages as individual POST requests.

Development

Run from the repository root:

pnpm install
pnpm --filter @framedash/mcp-server... build
pnpm --filter @framedash/mcp-server test

The trailing ... selects the MCP package plus its workspace dependencies, including @framedash/api-client, before compiling from a clean checkout.

License

MIT

Available Tools

12 tools
get_alert_historyGet Alert HistoryA

Get alert event history (trigger/resolve events).

Inputs: limit, project_id.

get_dashboardGet DashboardB

Get project dashboard metrics (KPIs, daily active users, top events).

Inputs: days, project_id.

get_funnelGet FunnelC

Analyze event funnels. Requires 2-8 event names as steps.

Inputs: steps (required), days, window, project_id.

get_heatmapGet HeatmapA

Get heatmap grid data for a map. Returns performance metrics per cell.

Inputs: map_id (required), days, cell_size, event_name, +1 more.

get_insightsGet InsightsC

Get aggregated insights for a metric grouped by a dimension.

Inputs: metric (required), group_by (required), days, limit, +2 more.

get_project_statusGet Project StatusB

Get the status of a project (event counts, last event time, etc.).

Inputs: project_id.

get_retentionGet RetentionC

Get player retention cohort analysis.

Inputs: days, project_id.

list_alertsList AlertsB

List all alert rules in the project.

Inputs: project_id.

list_contentList ContentA

List content registry entries (event names, display labels, etc.).

Inputs: type, project_id.

list_mapsList MapsB

List all maps in the project.

Inputs: project_id.

list_projectsList ProjectsA

Show the project bound to the current API key.

Inputs: no named parameters.

queryQuery EventsA

Execute a read-only SQL query against the ClickHouse events table. Returns up to limit rows (default 100, max 1000).

Inputs: sql (required), limit, project_id.

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    TDQS

    B3.4/5.0

    Scored across 12 tools

    Disambiguation3/5

    The specialized analytics tools (get_retention, get_funnel, get_insights, etc.) have distinct purposes, but the generic `query` tool can duplicate any of them via SQL, causing potential misselection. Additionally, `get_dashboard` and `get_insights` both surface aggregated metrics, so their boundaries are not perfectly crisp.

    Naming Consistency4/5

    Most tools follow a consistent `get_<resource>` or `list_<entity>` pattern, making names predictable. However, `query` stands out as a bare verb without a noun, breaking the otherwise uniform convention.

    Tool Count5/5

    12 tools is within the well-scoped range for a telemetry server. Each tool serves a clear analytics function, and none feel redundant or unnecessary.

    Completeness4/5

    The tool surface covers the core analytics domain: raw query, dashboards, retention, funnels, insights, heatmaps, projects, maps, content registry, and alert history. Gaps include lack of alert CRUD and project management operations, but for a read-only telemetry MCP server, the coverage is strong.

    Maintenance

    ActivityActive
    ResponsivenessNo recent community issues

    Related MCP Connectors

    Related MCP Servers

    • A
      license
      Not graded
      quality
      D
      maintenance
      MCP-Server from your Database optimized for LLMs and AI-Agents. Supports PostgreSQL, MySQL, ClickHouse, Snowflake, MSSQL, BigQuery, Oracle Database, SQLite, ElasticSearch, DuckDB
      550
      Apache 2.0
    • A
      license
      Not graded
      quality
      D
      maintenance
      MCP server for xeve.io that enables AI assistants to query personal analytics including productivity, coding, health, music, and GitHub activity.
      13 npm
      MIT
    • A
      license
      A
      quality
      F
      maintenance
      Unofficial MCP server that lets AI agents query Aptabase analytics using cookie-authenticated dashboard endpoints, providing tools for metrics, events, and sessions.
      17
      1
      MIT