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