MCP Server

The Framedash MCP Server is a Model Context Protocol server that gives LLMs direct access to Framedash telemetry data. It provides 12 read-only tools and 4 resources, enabling natural-language queries against your game analytics.

Setup

Claude Desktop

Add to your claude_desktop_config.json:

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

VS Code (Claude Extension)

Add to your VS Code settings:

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

Environment Variables

Variable	Required	Description
`FRAMEDASH_API_KEY`	Yes	Admin API key (`fd_admin_` prefix)
`FRAMEDASH_PROJECT_ID`	No	Default project UUID
`FRAMEDASH_BASE_URL`	No	API base URL (default: `https://app.framedash.dev`)

Tools

Query

Tool	Description	Arguments
`query`	Execute a read-only SQL query against the ClickHouse events table	`sql` (string, required), `project_id` (uuid, optional), `limit` (int 1-1000, default 100)

Analytics

Tool	Description	Arguments
`get_dashboard`	Project KPIs (DAU, MAU, sessions, events)	`project_id` (uuid, optional), `days` (7/14/30/90, default 30)
`get_retention`	Cohort retention analysis	`project_id` (uuid, optional), `days` (7/14/30/90, default 30)
`get_funnel`	Event funnel analysis	`project_id` (uuid, optional), `steps` (string, required: comma-separated 2-8 event names), `days` (7/14/30/90, default 30)
`get_insights`	Aggregated insights by dimension	`project_id` (uuid, optional), `metric` (count/unique_players, required), `group_by` (string, required: event_name, platform, etc.), `days` (7/14/30/90, default 30), `limit` (10/20/50), `event_name` (string, optional)
`get_heatmap`	Heatmap grid data for a map	`project_id` (uuid, optional), `map_id` (string, required), `cell_size` (5/10/25/50, default 25), `days` (1/7/14/30, default 7), `event_name` (string, optional)

Project

Tool	Description	Arguments
`list_projects`	Show projects bound to the API key	(none)
`get_project_status`	Project health overview (event counts, last event time)	`project_id` (uuid, optional)
`list_maps`	List maps in the project	`project_id` (uuid, optional)
`list_content`	List content registry entries	`project_id` (uuid, optional), `type` (string, optional)

Alerts

Tool	Description	Arguments
`list_alerts`	List alert rules	`project_id` (uuid, optional)
`get_alert_history`	Alert trigger/resolve history	`project_id` (uuid, optional), `limit` (int 1-100, default 50)

Resources

Data is also available as MCP resources via the framedash:// URI scheme:

URI	Description
`framedash://projects`	Projects bound to the API key
`framedash://projects/{projectId}/maps`	Maps with coordinates and bounds
`framedash://projects/{projectId}/content`	Content registry entries
`framedash://projects/{projectId}/status`	Project health and statistics

Example Prompts

Once the MCP Server is configured, you can query your data in natural language:

Prompt	Tool Used
”Show me DAU for the last 7 days”	`get_dashboard` (days=7)
“Analyze the funnel from spawn to death”	`get_funnel` (steps=“player.spawn,player.death”)
“Break down event counts by platform”	`get_insights` (metric=count, group_by=platform)
“Show the FPS heatmap for my map”	`get_heatmap` (map_id=…)
”Check recent alert history”	`get_alert_history`

Next Steps

API Reference — REST API details
CLI Reference — Command-line tool