Framedash Game Telemetry MCP Server
This MCP server lets LLM-powered tools query read-only Framedash game telemetry and analytics data.
Execute read-only SQL
SELECTqueries against the ClickHouse events table, with row limits.Retrieve project dashboard KPIs, DAU/MAU/session/event summaries, and top events.
Analyze player retention cohorts and event funnels with configurable time windows.
Get aggregated event insights grouped by dimensions such as event name or platform.
Fetch heatmap grid data for maps with performance metrics per cell.
Inspect the API-key-bound project and project health/status.
List maps, content registry entries, alert rules, and alert trigger/resolve history.
Use optional
project_idoverrides, with a default project ID configurable by environment variable.
@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 |
| Yes | API key with |
| No | Default project UUID for project-scoped tools |
| No | API base URL (default: |
If FRAMEDASH_PROJECT_ID is omitted, project-scoped tools still work but
require an explicit project_id argument per call.
Tools
Tool | Description |
| Execute SQL analytics query (SELECT only, limit default 100) |
| Project KPI summary (DAU, MAU, sessions, events) |
| Cohort retention data |
| Funnel analysis for event steps |
| Event insights with grouping |
| Heatmap grid data for a map |
| Show the project bound to the API key |
| Project health overview |
| List maps in a project |
| List content registry entries |
| List alert rules |
| Alert trigger history |
| List builds or find an exact build ID |
| 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 |
|
| Optional |
|
| Required distinct |
|
| Legacy text remains unchanged. |
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 |
| Project bound to the API key |
| Map list with bounds |
| Content registry |
| 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 testThe trailing ... selects the MCP package plus its workspace
dependencies, including @framedash/api-client, before compiling from a clean
checkout.
License
MIT
Available Tools
12 toolsget_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
Scored across 12 tools
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.
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.
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.
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
Related MCP Connectors
Analytics and debugging for your MCP server — explore usage and sessions, then root-cause errors.
Analytics for MCP servers. Query your tool calls, first-call success, retries and schema cost.
Make games with AI: one MCP server that connects your agent to Unity, Unreal and Godot editors.
Analytics for MCP servers. Find out which of your tools agents get wrong. MCPulse shows you which tools AI agents retry, which come back empty, and which they never call at all. Two lines inside your own server. It never sees your arguments or your results. getmcpulse.com
Related MCP Servers
- AlicenseNot gradedqualityDmaintenanceMCP-Server from your Database optimized for LLMs and AI-Agents. Supports PostgreSQL, MySQL, ClickHouse, Snowflake, MSSQL, BigQuery, Oracle Database, SQLite, ElasticSearch, DuckDB550Apache 2.0
- AlicenseNot gradedqualityDmaintenanceMCP server for xeve.io that enables AI assistants to query personal analytics including productivity, coding, health, music, and GitHub activity.13 npmMIT
- AlicenseAqualityFmaintenanceUnofficial MCP server that lets AI agents query Aptabase analytics using cookie-authenticated dashboard endpoints, providing tools for metrics, events, and sessions.171MIT
- FlicenseNot gradedqualityDmaintenanceMCP server that wraps Nightjar's analytics API, enabling Claude Code to query events, funnels, dashboards, and metrics through natural language.-