Framedash Mcp Server

io.github.crane-valleyPublished by GitHub account crane-valleyv0.2.0Updated Nov 5, 2026

MCP server for Framedash game telemetry: query analytics, heatmaps, perf regressions, and alerts

VerifiedSTDIODesktop onlyDatabasesData & Analytics

Overview

AI-generated overview

Read-only MCP server for Framedash game telemetry, letting an assistant query analytics, retention, funnels, heatmaps and alerts.

What you can do
  • Run read-only SQL against the ClickHouse events table, with a row limit
  • Get dashboard KPIs, retention cohorts, funnel analysis and grouped metric insights
  • Retrieve heatmap grid data per map cell in engine world coordinates
  • List projects, project status, maps, content registry entries and alert rules
  • Read alert trigger and resolve history
When to use it
Useful when a game team already tracks telemetry in Framedash and wants an assistant to answer questions about player activity, retention, funnels, map performance or alerts without leaving the chat.
Requirements
Runs locally over stdio, typically via npx from the npm package. Needs a Framedash API key in FRAMEDASH_API_KEY; the raw query tool also requires the data:admin scope. Optional FRAMEDASH_PROJECT_ID sets a default project, and FRAMEDASH_BASE_URL overrides the API base URL. Network access to the Framedash API is required.
Before you install
The API key is a secret placed in the client configuration; the raw query tool needs the broader data:admin scope, so prefer a key limited to analytics:read where possible. All tools are described as read-only, but queries still send project data to the Framedash API and results into the assistant conversation.

Installation

In SourceWeft

  1. Open Framedash Mcp Server in the dashboard and add it to a workspace.
  2. Enable the server for the chats that should use its tools.

Desktop only via STDIO. STDIO servers start a local process, so they need the SourceWeft desktop host.

Other MCP clients

Follow the launch instructions in the repository.

README

@framedash/mcp-server

MCP (Model Context Protocol) server for the Framedash game telemetry platform. Provides 12 read-only tools and 4 resources for querying analytics data from LLM-powered tools.

Setup

Claude Desktop

Add to your claude_desktop_config.json:

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:

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

Environment Variables

VariableRequiredDescription
FRAMEDASH_API_KEYYesAPI key with analytics:read for the aggregate tools; the raw query tool additionally requires data:admin
FRAMEDASH_PROJECT_IDNoDefault project UUID for project-scoped tools
FRAMEDASH_BASE_URLNoAPI 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

ToolDescription
queryExecute SQL analytics query (SELECT only, limit default 100)
get_dashboardProject KPI summary (DAU, MAU, sessions, events)
get_retentionCohort retention data
get_funnelFunnel analysis for event steps
get_insightsEvent insights with grouping
get_heatmapHeatmap grid data for a map
list_projectsShow the project bound to the API key
get_project_statusProject health overview
list_mapsList maps in a project
list_contentList content registry entries
list_alertsList alert rules
get_alert_historyAlert trigger history

Resources

URIDescription
framedash://projectsProject bound to the API key
framedash://projects/{projectId}/mapsMap list with bounds
framedash://projects/{projectId}/contentContent registry
framedash://projects/{projectId}/statusProject 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:

bash
pnpm installpnpm --filter @framedash/mcp-server... buildpnpm --filter @framedash/mcp-server test

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

License

MIT

Source: README.md at commit 207298c

Tools

12

query

Query Events

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

Parameterssqlrequiredlimitproject_id

get_dashboard

Get Dashboard

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

Parametersdaysproject_id

get_retention

Get Retention

Get player retention cohort analysis.

Parametersdaysproject_id

get_funnel

Get Funnel

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

Parametersdaysstepsrequiredwindowproject_id

get_insights

Get Insights

Get aggregated insights for a metric grouped by a dimension.

Parametersdayslimitmetricrequiredgroup_byrequiredevent_nameproject_id

get_heatmap

Get Heatmap

Get heatmap grid data for a map. Returns performance metrics per cell in engine world coordinates. For a map whose list_maps upAxis is "y" (Unity, Godot), the ground cell is x/z and y is omitted; otherwise it is x/y.

Parametersdaysmap_idrequiredcell_sizeevent_nameproject_id

list_projects

List Projects

Show the project bound to the current API key.

Takes no parameters.

get_project_status

Get Project Status

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

Parametersproject_id

list_maps

List Maps

List all maps in the project.

Parametersproject_id

list_content

List Content

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

Parameterstypeproject_id

list_alerts

List Alerts

List all alert rules in the project.

Parametersproject_id

get_alert_history

Get Alert History

Get alert event history (trigger/resolve events).

Parameterslimitproject_id

Version history

3
  1. v0.2.0LatestNov 4, 2026
  2. v0.1.5Sep 25, 2026
  3. v0.1.4Sep 16, 2026

Score

90% of the applicable checks met

How complete this listing is, computed from the registry entry, the endpoint and public sources. Not a rating of the server and not a statement that it is safe or working today: reachability is a dated check, and no installs or reviews go into the score.

  • Reached in the last 30 days25 pts
  • Auth declared10 pts

    Declare the credential headers in the registry entry, or keep the endpoint answering the probe so its auth can be classified.

  • Tools listedRequired15 pts
  • DescriptionRequired15 pts
  • Logo10 pts
  • Documentation15 pts
  • License10 pts