Clarity MCPの使い方｜Claude Codeに行動データを読ませる手順

Clarity MCPとは、Microsoft Clarityのダッシュボード集計とセッション録画を、Claude CodeなどのAIから直接読み取れるようにするMicrosoft公式のMCPサーバーです。「先週からスマホの離脱が増えたページは？」「このページで無反応クリックが多いのはどこ？」といった質問を日本語で投げると、AIがClarityのデータを取りに行って答えます。

Clarityは無料で録画まで取れる便利なツールですが、毎回ダッシュボードを開いてフィルターを組み、録画を1本ずつ再生するのは手間がかかります。結果として「入れたけれど見ていない」状態になりがちです。MCPでつなぐと、確認したいことを質問するだけで数字と録画の要約が返ってくるため、見る頻度を上げられます。

この記事では、Clarity MCPで取れるデータの範囲、Claude Codeへの接続手順、最初に聞くとよい質問を整理します。後半では、当サイトcodequest.workの直近3日分を実際にClaude Codeで見た結果を使って、集計の数字と録画が食い違ったときの確かめ方まで解説します。Clarityそのものの導入がまだの方は、先にMicrosoft Clarityの導入と使い方をご覧ください。記載の内容は2026年10月7日時点の情報です。

Clarity MCPとは｜できることと3つのツール

Clarity MCPは、Clarityのダッシュボード集計とセッション録画の情報を、MCP（Model Context Protocol）という共通の接続方式でAIに渡す仕組みです。MicrosoftがGitHubのmicrosoft/clarity-mcp-serverでMITライセンスのオープンソースとして公開しており、npmパッケージ @microsoft/clarity-mcp-server として配布されています（2026年10月7日時点の最新版は2.0.1）。

サーバーが提供するツールは次の3つです。AIは質問の内容に応じて、このうちどれを使うかを自分で選びます。

ポイントは、集計の質問が自然言語のまま渡せることです。query-analytics-dashboardは「Top pages by dead clicks last 3 days」のような文章を受け取り、サーバー側で集計クエリに変換して結果を返します。フィルターの組み方を覚えなくても、聞きたいことをそのまま書けば数字が出てきます。

取れるデータの範囲と制限

現行のClarity MCP（2.x）は、ClarityがMCP用に用意した専用の窓口からデータを取るため、Data Export APIの「直近1〜3日」の制限には縛られません。npmで配布されているv2.0.1のソースでは、集計・録画・ドキュメントの問い合わせ先がすべて clarity.microsoft.com/mcp 配下になっています。Data Export APIを呼んで期間を1〜3日に限っていたのは旧版の1.x系で、「Clarity MCPは3日分しか見られない」という説明はこの旧版のものです。

当サイトで「直近14日の日別セッション数」を聞いたところ、14日間の期間として解釈され、日別のデータが返ってきました。一方で、1回の応答で返る行数は絞られることがあり、このときは「10行まで」という注記が付いていました。行数の多い集計は「上位10件」のように件数を指定して聞くと、結果が安定します。

Data Export APIの仕様は、Microsoft LearnのClarity Data Export APIに記載されています。MCP側の上限は公式に書かれていません。当サイトで試した日は集計の質問を6回、録画の一覧を2回呼んで、上限エラーは出ませんでした。それでも、同じ質問を言い換えて何度も投げるより、1回の質問で期間と分析軸をまとめて聞くのが安全です。

Clarity MCPがもっとも力を発揮するのは、施策を入れた直後や不具合の報告を受けたときに、直近のユーザーの動きを素早く確かめる場面です。数か月単位の推移はGA4やSearch Consoleのほうが扱いやすいので、そちらと分担すると効率的です。

Claude Codeに接続する手順

Claude Codeからつなぐ場合の手順は次のとおりです。所要時間は5分ほどです。

1. Clarityにログインし、対象プロジェクトの「Settings」→「Data Export」→「Generate new API token」を開く
2. トークン名（4〜32文字の英数字・ハイフン・アンダースコア・ピリオド）を付けて発行し、表示されたトークンを控える
3. ターミナルで下のコマンドを実行し、Claude CodeにMCPサーバーを登録する
4. Claude Codeを起動し、/mcp で clarity が接続済みになっていることを確認する

claude mcp add clarity -- npx -y @microsoft/clarity-mcp-server --clarity_api_token=発行したトークン

サイトを複数運営している場合は、Clarityのプロジェクトごとにトークンを発行し、clarity-サイト名 のように名前を分けて登録します。当サイトも、運営サイトごとに別名で登録しています。AIに質問するときに「codequestのClarityで」と指定でき、別サイトのデータを取り違えません。

Claude Desktopを使っている場合は、設定の「Extensions」で「Microsoft Clarity」を検索してインストールし、トークンを入力するだけで使えます。Claudeのコネクタ一覧にもMicrosoft Clarityコネクタとして掲載されています。MCPの登録方法やスコープの考え方をもう少し詳しく知りたい方は、Claude CodeのMCP・Hooks・Skills活用ガイドで解説しています。

最初に聞く5つの質問

Clarity MCPで最初に聞くべきなのは、「全体の数字」と「困っている兆候が出ているページ」です。いきなり録画を探すより、集計で当たりを付けてから録画を見る順番のほうが、少ない質問で原因にたどり着けます。当サイトで実際に使っている質問を5つ紹介します。

質問には期間を必ず入れます。期間を書かないと、AIが期間を補って解釈したり、聞き返されたりします。また、1つの質問に聞きたいことを詰め込みすぎると集計の変換がずれやすくなるため、上の表のように「1つの質問で1つの集計」にするのが基本です。

直近3日について、無反応クリック・連続クリック・quick backが1回以上あったページを、
セッション数・各クリック数・平均スクロール深度つきで上位10件出して

実例：codequest.workの3日分を見た結果

ここからは、2026年10月7日に当サイトのClarityをClaude Codeから見た実際の結果です。上の5つの質問を順に投げました。

サイト全体の数字

デバイス×チャネルでは、PCの自然検索が616セッションで最も多く、次がPCの「Other」178、スマホの自然検索141でした。開発者向けのサイトなので、PCからの検索流入が中心という傾向がそのまま出ています。

困っている兆候が出ていたページ

無反応クリックが多かったのは、JavaScriptの練習問題記事（3日で23回）と、ブラウザでコードを実行できるJavaScript練習問題クイズ（20回、連続クリック4回）でした。CSSのジェネレーター系ツールにも16〜17回ずつ出ていました。

一方、トップページは5セッション中4回、模写練習のカテゴリページは3セッション中3回がquick back（すぐに前のページへ戻る動き）でした。どちらもセッション数が少ないので、この時点では判断せず、継続して見る対象としてメモしています。

JavaScriptエラー

エラー文ごとに集計すると、「ResizeObserver loop completed with undelivered notifications.」が21回、「Script error.」が2回で、それ以外はありませんでした。どちらも対応が不要な種類のエラーでした。理由は後の章で説明します。

集計と録画が食い違うときの確かめ方

Clarity MCPの集計結果は、録画で裏を取ってから判断します。当サイトでは、集計の数字だけを見ていたら誤った結論を出すところでした。

無反応クリック237回の正体

練習問題記事と練習問題クイズの2ページについて「無反応クリックと連続クリックの多いクリック先は？」と聞いたところ、「▶ 実行する」ボタンに無反応クリックが237回、連続クリックが56回という結果が返ってきました。そのまま読めば「実行ボタンが反応していない」という重大な不具合です。

そこで同じ期間の練習問題クイズの録画を20件取り、行動を集計し直しました。結果は次のとおりです。

ページ別の集計と比べると、クリック先別の237回だけが桁違いに大きく、期間が3日より広く解釈されたか、集計単位がずれていた可能性が高いと判断しました。録画を見ると、20件中7件が30分以上操作を続けており、コードの入力も460回記録されていました。実行ボタンが反応していなかったとすると、ここまで長く問題を解き続ける行動は説明しにくくなります。

確かめるときの3つの手順

1. 返ってきた解釈を読む：query-analytics-dashboardの結果には、質問をどう解釈したか（期間・対象・集計単位）の説明が付いてきます。期間が意図どおりかをまず確認する
2. 別の聞き方で同じ数字を出す：ページ別とクリック先別のように、切り口を変えて同じ指標を聞き、桁が合うかを見る
3. 録画で裏を取る：数字が大きく出たページは、list-session-recordingsで録画を取り、タイムラインのイベントを数え直す

集計の変換はAIとサーバーが自動で行うため、人がフィルターを組むときより解釈のずれが入りやすくなります。「数字が大きすぎる」「ほかの数字と桁が合わない」と感じたら、その数字で判断する前に録画で確かめるのが原則です。

対応不要なJavaScriptエラーの見分け方

JSエラーの集計には、サイトの不具合ではないエラーも混ざります。当サイトで出た2種類は、どちらも対応不要と判断しました。

ResizeObserverのメッセージは、MDNのResizeObserverで、ブラウザが無限ループで固まるのを防ぐために、配りきれなかった通知を次の描画に回したときに出すものだと説明されています。「Script error.」については、MDNのscript要素に、CORSのチェックを通らない別ドメインのスクリプトはエラー情報が最小限しか渡されないと書かれています。

逆に、自サイトのファイル名が入ったエラーや、「クリックエラー」（クリック直後に起きたエラー）として記録されたものは、ユーザーの操作が失敗している可能性があります。Clarity MCPに「クリックエラーがあったセッションの録画を出して」と聞き、どのボタンで起きたかを確認してください。

録画データが大きすぎるときの読み方

list-session-recordingsは、録画1件ごとにクリック・入力・テキスト選択などのイベントを時系列ですべて返します。そのため件数を増やすとデータが一気に大きくなります。当サイトで練習問題クイズの録画を20件取ったときは、約57万文字になり、Claude Codeが一度に読める量を超えてファイルに保存されました。

この場合は、AIに全文を読ませるのではなく、保存されたファイルを集計させます。Claude Codeに「保存されたファイルをjqで集計して」と頼むと、次のような集計を自分で組んで実行します。

# 録画ごとの滞在時間・ページ数・クリック数
jq -r '.[] | "\(.timestamp) | \(.activeDuration) | pages=\(.pagesCount) | clicks=\(.sessionClickCount)"' recordings.json

# 対象ページで起きたイベントの種類と件数
jq -r '.[].timeline[] | select(.url != null and (.url | contains("/target-page/"))) | .timelineEvents[].eventtype' recordings.json | sort | uniq -c | sort -rn

録画の件数は、まず10〜20件から始めるのがおすすめです。並び順（新しい順・滞在時間の長い順・クリックの多い順など）と、「連続クリックがあったセッションだけ」「スマホだけ」といった絞り込みを指定できるため、件数を増やすより条件で絞ったほうが目的の録画にたどり着けます。

なお、録画のタイムラインに入るクリック先の文字や入力内容は、Clarityのマスキング設定に従って伏せ字で返ってきます。当サイトでも、クリックした文字の多くは「▪▪▪」のような記号に置き換わっていました。個人情報がAIに渡らないかが気になる場合は、Clarity側のマスキング設定を先に確認してください。設定の方法は導入記事のマスキングの章で解説しています。

GA4・Search ConsoleのMCPと組み合わせる

Clarity MCPは単体で使うより、GA4とSearch ConsoleのMCPと並べて使うと効果が大きくなります。3つは見ているものが違うためです。

当サイトでは、3つのMCPを同じClaude Codeに登録しています。「この記事は検索で表示されているのにクリックされない。GA4で滞在を見て、Clarityで読んだ人のスクロールを見て」と1回頼むだけで、3つのデータを横断して原因の候補を出してくれます。ダッシュボードを3つ開いて見比べる作業がなくなるのが、MCP連携の大きな利点です。

GA4の画面で数字を確認する方法はGA4のダッシュボード機能の使い方、ほかのツールのMCP連携はClaude CodeのMCP連携ガイド一覧にまとめています。

使うときの注意点

Clarity MCPを安全に使うために、次の3点を押さえておきます。

トークンをリポジトリに入れない

claude mcp add で登録したトークンは、Claude Codeの設定ファイルに平文で保存されます。チームで共有する .mcp.json（プロジェクトスコープ）に登録すると、リポジトリにトークンが入ってしまいます。個人の設定（既定のローカルスコープ）に登録し、プロジェクトのメンバーが外れたときはトークンを作り直してください。

問い合わせの回数を抑える

MCP側の1日の上限は公式に書かれていません。Data Export APIを直接呼ぶ場合は1プロジェクトあたり1日10回までで、超えると「429 TooManyRequests」が返ります。MCPでも、同じ質問を言い換えて何度も投げるより、最初の質問で期間と分析軸をまとめて指定してください。

数字だけで結論を出さない

前の章で見たとおり、自然言語からの集計は解釈がずれることがあります。修正や施策の判断に使う数字は、録画か別の切り口の集計で一度確かめてから使います。

まとめ

Clarity MCPを使うと、Clarityのダッシュボードを開かずに、質問するだけで直近のユーザーの動きを確認できます。要点は次の3つです。

• Clarity MCPは集計・録画・ドキュメントの3つのツールを持つ公式MCPサーバー。現行版の集計は1〜3日に限られない
• 最初は「全体の数字」と「困っている兆候が出ているページ」を聞き、気になったページだけ録画を見る
• 桁の合わない数字は、返ってきた解釈・別の切り口・録画の3つで確かめてから判断する

まずはトークンを発行してClaude Codeに登録し、「直近3日の概況を出して」と聞くところから始めてください。Clarityをまだ入れていない場合は、Microsoft Clarityの導入と使い方で設置から計測の確認までを解説しています。

よくある質問

Q. Clarity MCPは無料で使えますか？

はい。Clarity自体が無料で、Clarity MCPのサーバーもMITライセンスのオープンソースとして公開されています。ただし、質問を処理するClaudeなどのAI側の利用料は別にかかります。

Q. Claude Code以外のAIでも使えますか？

使えます。Claude Desktopでは設定の「Extensions」からインストールでき、VS CodeなどMCPに対応したほかのクライアントでも、同じnpmパッケージを登録すれば利用できます。

Q. 何日前までのデータを見られますか？

現行版（2.x）はData Export APIとは別の窓口を使うため、1〜3日の制限はかかりません。当サイトの実測では14日分の日別データを取得できました。ただし、取得できる最大の期間は公式に書かれていません。

Q. APIトークンは誰が発行できますか？

Clarityプロジェクトの管理者だけが発行できます。発行場所はプロジェクトの「Settings」→「Data Export」です。

Q. ヒートマップの画像もAIに見せられますか？

Clarity MCPのツールには、ヒートマップの画像を返すものはありません。録画は再生リンクとクリックや入力のタイムラインが返るので、画像で確認したいときは返ってきたリンクからClarityの画面を開きます。

Q. MCPで出た数字がダッシュボードと合わないのはなぜですか？

質問を自然言語から集計クエリに変換する際に、期間や集計単位の解釈がずれることがあるためです。返ってきた結果に付く解釈の説明を確認し、必要なら期間を明記して聞き直してください。

関連記事

• Microsoft Clarityの導入と使い方｜ヒートマップで直す手順
• Claude CodeのMCP連携ガイド一覧｜Figma・WordPress・Chrome DevTools・Notion
• Chrome DevTools MCPの使い方｜Claude Codeにブラウザ実測・デバッグさせる方法
• MCPサーバーの作り方｜Claude Codeから呼べる自作ツールを実装する
• GA4のダッシュボード機能の使い方｜＋作成ボタンと6種のグラフ
• GA4設置後の動作確認｜計測が効いているか自分で確かめる手順