MCP Server

Framedash MCP Server は、LLM（大規模言語モデル）から Framedash のテレメトリデータに直接アクセスするための Model Context Protocol サーバーです。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"
      }
    }
  }
}

Windows では "command": "npx" を "command": "cmd" に変更し、args 配列の先頭に "/c" を追加してください:

"command": "cmd",
"args": ["/c", "npx", "-y", "@framedash/mcp-server"]

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

すべてのツール（raw SQL の query を含む）を利用するには Full プリセットキーを、raw SQL 以外の分析ツールには Read-only キーを使用してください。

ホスト型リモートエンドポイント

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 フローを自力で完了できます。ツール呼び出しは、REST API と同じく、付与された scope とプロジェクトの範囲で実行されます。 GET と DELETE は 405 を返します。 raw SQL の query ツールはリモートエンドポイントでは使えません。これは data:admin scope を必要とし、OAuth トークンはこれを持てないためです。 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 を設定すると、LLM に自然言語で問い合わせできます:

プロンプト例	使用されるツール
「過去 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