MCP Server

Framedash MCP Server 是一个 Model Context Protocol 服务器，可让 LLM 直接访问 Framedash 遥测数据。提供 12 个只读工具和 4 个资源，支持使用自然语言查询游戏分析数据。

设置

Claude Desktop

在 claude_desktop_config.json 中添加：

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

VS Code (Claude Extension)

在 VS Code 设置中添加：

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

Claude Code

使用 claude mcp 命令注册服务器：

claude mcp add framedash \
  -e FRAMEDASH_API_KEY=fd_xxx \
  -e FRAMEDASH_PROJECT_ID=your-project-uuid \
  -- npx -y @framedash/mcp-server

使用 Full 预设密钥可启用所有工具（包括 raw SQL query），使用 Read-only 密钥可用于 raw SQL 以外的分析工具。

托管远程端点

Framedash 还托管了一个远程 MCP 服务器，因此支持远程服务器和 OAuth 的 MCP 客户端无需本地安装。请通过 Streamable HTTP 传输向 POST {origin}/api/mcp（默认 https://app.framedash.dev/api/mcp）发送请求。该端点是无状态的：不使用会话 ID。

认证仅支持 OAuth 2.1 Bearer；此处不接受 API 密钥。401 响应会带有 WWW-Authenticate 头，其 resource_metadata 指向 {origin}/.well-known/oauth-protected-resource，因此实现了 MCP 授权规范的客户端可以自行发现授权服务器并完成 OAuth 流程，包括动态客户端注册。工具调用在已授予的 scope 和项目范围内执行，与 REST API 一致。GET 和 DELETE 返回 405。raw SQL query 工具在远程端点上不可用：它需要 data:admin scope，而 OAuth 令牌绝不会携带该 scope，因此 raw SQL 仍需使用 stdio 服务器和 Full API 密钥。

除了按账户的计划速率限制之外，远程端点在其认证前入口处还有一个独立的按 IP 速率限制。详情参见 API 概览中的速率限制。

对于支持远程服务器和 OAuth 的 MCP 客户端，可将此托管端点作为 stdio 服务器的免安装替代方案。对于基于 API 密钥或本地的配置，仍应选择 stdio 服务器（npx -y @framedash/mcp-server）。

环境变量

变量	必须	说明
`FRAMEDASH_API_KEY`	是	具备 MCP 工具所需 scope 的 API 密钥。Full 预设允许包括 raw SQL `query` 在内的所有工具，Read-only 预设允许除 raw SQL 外的分析工具。
`FRAMEDASH_PROJECT_ID`	否	默认项目 UUID
`FRAMEDASH_BASE_URL`	否	API 基础 URL（默认：`https://app.framedash.dev`）

工具

查询

工具	说明	参数
`query`	对 ClickHouse events 表执行只读 SQL 查询	`sql` (string, 必须), `project_id` (uuid, 可选), `limit` (int 1-1000, 默认 100)

分析

工具	说明	参数
`get_dashboard`	项目 KPI（DAU、MAU、会话、事件数）	`project_id` (uuid, 可选), `days` (7/14/30/90, 默认 30)
`get_retention`	同期群留存分析	`project_id` (uuid, 可选), `days` (7/14/30/90, 默认 30)
`get_funnel`	事件漏斗分析	`project_id` (uuid, 可选), `steps` (string, 必须: 逗号分隔 2-8 个事件名), `days` (7/14/30/90, 默认 30)
`get_insights`	按维度汇总的洞察	`project_id` (uuid, 可选), `metric` (count/unique_players, 必须), `group_by` (string, 必须: event_name, platform 等), `days` (7/14/30/90, 默认 30), `limit` (10/20/50), `event_name` (string, 可选)
`get_heatmap`	地图的热力图网格数据	`project_id` (uuid, 可选), `map_id` (string, 必须), `cell_size` (5/10/25/50, 默认 25), `days` (1/7/14/30, 默认 7), `event_name` (string, 可选)

项目

工具	说明	参数
`list_projects`	显示 API 密钥关联的项目	无
`get_project_status`	项目健康概览（事件数、最后事件时间）	`project_id` (uuid, 可选)
`list_maps`	项目中的地图列表	`project_id` (uuid, 可选)
`list_content`	内容注册表条目列表	`project_id` (uuid, 可选), `type` (string, 可选)

告警

工具	说明	参数
`list_alerts`	告警规则列表	`project_id` (uuid, 可选)
`get_alert_history`	告警触发/解除历史	`project_id` (uuid, 可选), `limit` (int 1-100, 默认 50)

资源

通过 framedash:// URI 方案以 MCP 资源方式访问数据：

URI	说明
`framedash://projects`	API 密钥关联的项目
`framedash://projects/{projectId}/maps`	包含坐标和范围的地图列表
`framedash://projects/{projectId}/content`	内容注册表条目
`framedash://projects/{projectId}/status`	项目状态和统计

使用示例

配置 MCP Server 后，可以使用自然语言查询数据：

示例提示	使用的工具
”显示过去 7 天的 DAU”	`get_dashboard` (days=7)
“分析从 spawn 到 death 的漏斗”	`get_funnel` (steps=“player_spawn,player_death”)
“按平台统计事件数”	`get_insights` (metric=count, group_by=platform)
“显示地图的 FPS 热力图”	`get_heatmap` (map_id=…)
”查看最近的告警历史”	`get_alert_history`

下一步

API 参考: REST API 详细信息
CLI 参考: 命令行工具

面向 AI 代理: llms.txt