Clarity MCP Server

🚀 Microsoft Clarity Data Export MCP Server

このサーバーは、Microsoft ClarityのデータエクスポートAPI用のModel Context Protocol (MCP) サーバーです。Claude for Desktopやその他のMCP互換クライアントを使用して、Clarityから分析データを取得できます。

✨ 主な機能

• シンプルなインターフェイスを通じて、Microsoft Clarityの分析データをクエリできます。
• 最大3つの次元（ブラウザ、デバイス、国/地域、OSなど）でフィルタリングできます。
• さまざまなメトリクス（スクロール深度、エンゲージメント時間、トラフィックなど）を取得できます。
• Claude for Desktopやその他のMCPクライアントとシームレスに統合されます。

📦 インストール

前提条件

• Node.js v16以上
• Microsoft ClarityアカウントとAPIトークン
• 任意のMCP互換クライアント（Claude for Desktopなど）

インストール方法

オプション1: npmを使用したインストール（推奨）

npmを使用して、このパッケージを直接インストールして実行できます。

# グローバルにインストール
npm install -g @microsoft/clarity-mcp-server

# サーバーを起動
clarity-mcp-server

オプション2: npxを使用してインストールせずに実行

npxを使用して、インストールせずにサーバーを直接実行できます。

npx @microsoft/clarity-mcp-server

どちらのオプションでも、--clarity_api_token パラメータを使用してClarity APIトークンを指定できます。

npx @microsoft/clarity-mcp-server --clarity_api_token=your-token-here

オプション3: 手動インストール

1. このリポジトリをクローンまたはダウンロードします。
2. 依存関係をインストールします。

   npm install
   

3. TypeScriptコードをビルドします。

   npm run build
   

4. サーバーを起動します。

   npm start
   

📚 ドキュメント

設定方法

ClarityデータエクスポートAPI トークンは、以下の2つの方法で指定できます。

1. コマンドライン引数:

   npx @microsoft/clarity-mcp-server --clarity_api_token=your-token
   

2. ツールパラメータ:
   • get-clarity-data ツールを呼び出す際に、token をパラメータとして指定します。

MCPクライアントの設定

汎用MCPクライアントの設定

MCPクライアントは、通常、サーバーに接続するための設定が必要です。以下は、MCPクライアントを設定する一般的な例です。

{
  "mcpServers": {
    "@microsoft/clarity-mcp-server": {
      "command": "npx",
      "args": [
        "@microsoft/clarity-mcp-server",
        "--clarity_api_token=your-api-token-here"
      ]
    }
  }
}

この設定を追加する場所と方法の詳細は、使用するMCPクライアントによって異なります。

Claude for Desktopの設定

Claude for Desktopをこのサーバーを使用するように設定するには、以下の手順を実行します。

1. Claude for Desktopの設定ファイルを開きます。
   • Windows: %AppData%\Claude\claude_desktop_config.json
   • macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
2. 上記の汎用例に示されている設定を追加します。
3. 設定ファイルを保存し、Claude for Desktopを再起動します。

サーバーの使用方法

このサーバーが設定されたMCPクライアントを使用すると、Clarityデータを取得するように要求できます。例えば： "Can you fetch my Clarity data for the last day, filtered by Browser and showing Traffic metrics?" MCPクライアントは、get-clarity-data ツールを実行するように促します。このツールには、以下が必要です。

• numOfDays: 取得する日数（1 - 3）
• dimensions: フィルタリングする次元の配列（オプション）
• metrics: 取得するメトリクスの配列（オプション） コマンドライン引数で資格情報を設定していない場合は、以下も提供する必要があります。
• token: あなたのClarity APIトークン

APIトークンの取得方法

APIトークンを生成するには、以下の手順を実行します。

1. あなたのClarityプロジェクトにアクセスします。
2. 設定 -> データエクスポート -> 新しいAPIトークンを生成 を選択します。
3. トークンに説明的な名前を付けます。
4. 生成されたトークンを安全に保存します。

制限事項

• プロジェクトごとに1日に最大10回のAPIリクエストが許可されます。
• データの取得は過去1日から3日までに限定されます。
• 1つのリクエストで最大3つの次元を渡すことができます。
• レスポンスは最大1,000行に制限され、ページネーションはできません。

📄 ライセンス

MIT