Umami Analytics MCP サーバー

Umamiのウェブサイト分析データへのアクセスを提供することで、Claudeの機能を強化するModel Context Protocol（MCP）サーバー。このサーバーにより、Claudeはユーザー行動の分析、ウェブサイトのパフォーマンスの追跡、データに基づくインサイトの提供が可能になります。

コードベースは最初から最後まで Claude Sonnet 3.5 と Cursor を使用して生成されました。

何をするのか

このサーバーは、Claude を Umami 分析プラットフォームに接続し、次のことを可能にします。

• ユーザーの行動経路と行動パターンを分析する
• ウェブサイトのパフォーマンス指標を追跡する
• リアルタイムの訪問者アクティビティを監視する
• ウェブページのコンテンツをキャプチャして分析する
• 過去の分析データから洞察を生成する

仕組み

サーバーは、Claude が Web サイトのデータを分析するために次のツールを提供します。

利用可能なツール

• get_websites : Umamiアカウント内のウェブサイトとそのIDのリストを取得します
• get_website_stats : ウェブサイトのページビュー、訪問者数、直帰率などの主要な指標を取得します
• get_website_metrics : URL、リファラー、ブラウザ、国などの特定の指標を分析します
• get_pageview_series : カスタマイズ可能な間隔で時系列ページビューデータを取得する
• get_active_visitors : ウェブサイトの現在のアクティブ訪問者数を監視する
• get_session_ids : 特定のイベントまたは期間のセッションIDを取得します。
• get_tracking_data : 特定のセッションIDの詳細なアクティビティデータを取得する
• get_docs : 多くのユーザージャーニーでセマンティック検索を実行し、特定の質問に最も関連性の高いチャンクを返します。
• get_screenshot : ウェブページのビジュアルスナップショットをキャプチャする
• get_html : ウェブページの HTML ソースコードを取得して分析する

各ツールには説明と、渡せる引数のリストがあります。これらは、Claude がジョブに適したツールを効果的に選択し、適切なパラメータを指定できるようにするためのコンテキストと情報を提供するために使用されます。

これらのツールのほとんどは、Umami APIからClaude Desktopに直接データを取得しますが、get_docsはセマンティック検索ステップを追加することで、Claudeのコンテキストウィンドウの問題を回避し、トークンの使用量を節約します。特定のイベントにおけるすべてのユーザージャーニーはUmami APIを使用して取得され、それらは小さなセクションに分割され、Hugging Faceのオープンソースセンテンストランスフォーマーモデルを使用して埋め込まれます。その後、質問に基づいて最も関連性の高いチャンクが取得され、Claudeに返されます。これにより、ユーザーがWebサイトで実行した特定のアクションや行動を分析することができ、従来のデータ視覚化ツールでは再現が困難です。この埋め込みとセマンティック検索の実装はsrc/analytics_service/embeddings.pyファイルにあります。

さらに、get_screenshotツールとget_htmlツールは、オープンソースのCrawl4AIウェブクローラーを使用して、指定されたウェブサイトのHTMLソースコードとスクリーンショットを取得します。Claudeのコンテキストウィンドウの問題を回避するため、スクリーンショットはサイズを縮小するためにダウンサンプリングする必要があります。これにより、ウェブサイトの構造と外観に関するコンテキストをClaudeに提供でき、サイトパフォーマンス改善に関するより正確で適切な推奨事項を提供できるようになります。ウェブクローラーの実装はsrc/analytics_service/crawler.pyファイルにあります。

セットアップガイド

前提条件

• uvをインストール: pip install uv

1. クロードデスクトップ構成Claude Desktop 構成ファイルに以下を追加します。
   • MacOS: ~/Library/Application Support/Claude/claude_desktop_config.json
   • Windows: %APPDATA%/Claude/claude_desktop_config.json
   { "mcpServers": { "analytics_service": { "command": "uv", "args": [ "--directory", "/path/to/analytics_service", "run", "analytics-service" ], "env": { "UMAMI_API_URL": "https://example.com", "UMAMI_USERNAME": "yourUmamiUsername", "UMAMI_PASSWORD": "yourUmamiPassword", "UMAMI_TEAM_ID": "yourUmamiTeamId" } } } }

   /path/to/analytics_service analytics_service ディレクトリへの実際のパスに置き換えます。

   UMAMI_API_URL のhttps://example.com 、ご利用の Umami のバージョン（セルフホストまたは Umami Cloud ホスト）の URL に置き換えてください。UMAMI_USERNAME と UMAMI_PASSWORD のyourUmamiUsernameとyourUmamiPasswordを、Umami アカウントの認証情報に置き換えてください。UMAMI_TEAM_ID のyourUmamiTeamId 、分析対象のチームの ID に置き換えてください。

2. クロードデスクトップを開く

Claude Desktop を開くと、自動的に analytics_service MCP サーバーへの接続が開始されます。サーバーの初期化と適切なパッケージのインストールには数分かかる場合があります。サーバーの準備が完了すると、チャットウィンドウの右下に利用可能な MCP ツールが 10 個表示されます。これは、小さなハンマーのアイコンとその横に 10 という数字で示されます。

さらに、まだ設定されていない場合は、Claude Desktop の「機能プレビュー」で「分析ツール」を有効にすることを強くお勧めします。これにより、Claude はダッシュボードやその他のデータ可視化ツールを作成できるようになります。設定するには、左側のパネルで「機能プレビュー」タブを見つけ、その中で「分析ツール」を有効にしてください。LaTeX レンダリングも同じセクションで有効にできます。

サーバーの使い方

はじめる

最も簡単な方法は、サーバーが提供するダッシュボード作成プロンプトを使用することです。これは、チャットウィンドウの左下にある「MCPから添付」添付ボタンをクリックして選択できます。次に、実装を選択し、「ダッシュボード作成プロンプト」を選択してください。

これは、次のことを尋ねながら、Web サイトのダッシュボードを作成するプロセスをガイドします。

1. 分析したいウェブサイトの名前
2. 分析の開始日と終了日
3. ウェブサイトのタイムゾーン

これらの情報を入力すると、サーバーはClaudeにダッシュボードの構築方法を指示するtxtファイルを生成します。チャットウィンドウでEnterキーを押すと、Claudeが残りの作業を行います。その後、Claudeにダッシュボードの変更や他のビジュアライゼーションの追加を依頼できます。

自然言語の使用

よりカスタマイズ性の高いエクスペリエンスをご希望の場合は、クロードに直接お問い合わせいただき、ダッシュボードに表示するデータや使用するビジュアライゼーションなど、お客様独自の要件をご指定いただけます。さらに、ユーザージャーニーを分析して具体的な問題点を特定したり、サイトのスクリーンショットを追加してクロードに詳細なコンテキストを提供したりすることも可能です。

リクエストを完了するために必要なツールは、Claudeが自動的に使用します。自然な言葉でリクエストするだけで、Claudeが使用するツールを決定します。利用可能なすべてのツールのリストを確認したい場合は、Claudeにリストを表示するように依頼するか、チャットウィンドウの右下にあるハンマーアイコンをクリックしてください。

独自のプロンプトを作成する

定期的に使用するワークフロー用に独自のプロンプトを作成することもできます。これを行うには、以下の手順が必要です。

1. プロンプト構造を定義する次の内容を含むプロンプト定義を作成します。
   • name : プロンプトの一意の識別子
   • description : プロンプトが何をするかの明確な説明
   • arguments : プロンプトに必要な入力パラメータのリスト

   src/analytics_service/server.pyのlist_prompts()関数に以下を追加します。

   構造例:

   @app.list_prompts() async def list_prompts(): return [ # ... existing prompts ... { "name": "Your Prompt Name", "description": "Your prompt description", "arguments": [ { "name": "Parameter Name 1", "description": "Parameter description", "required": True/False }, { "name": "Parameter Name 2", "description": "Parameter description", "required": True/False } ] } ]
2. プロンプトを実装するsrc/analytics_service/server.pyのget_prompt()関数にプロンプト処理ロジックを追加します。
   @app.get_prompt() async def get_prompt(name: str, arguments: Any): # ... existing prompts ... if name == "Your Prompt Name": return { "messages": [ { "role": "user", "content": { "type": "text", "text": f"Your prompt template with {arguments['Parameter Name']}" } } ] }
   プロンプトでメッセージを定義するとき、会話を構成するためにroleフィールドが重要になります。
   • ユーザーの入力や質問をシミュレートするメッセージには"role": "user"を使用します
   • クロードの返答や指示を表すメッセージには"role": "assistant"を使用します
   • コンテキストを設定したり、高レベルの指示を提供するメッセージには"role": "system"を使用します。

   各メッセージのcontentフィールドにはtypeを指定する必要があります。使用可能なタイプは次のとおりです。

   • "type": "text" - プレーンテキストコンテンツの場合
   • "type": "resource" - ファイル、ログ、その他のデータなどの外部リソースを含める場合。以下の要素を含むresourceオブジェクトを含める必要があります。
     • uri : リソース識別子
     • text :実際の内容
     • mimeType : コンテンツのMIMEタイプ（例："text/plain"、"text/x-python"）

   リソースにはtextフィールドにコンテンツが含まれますが、 resourceタイプを使用すると、次のようないくつかの重要な利点があります。

   1. コンテンツタイプの認識: mimeTypeフィールドは、Claude にコンテンツをどのように解釈するかを伝えます (例: Python コード、プレーンテキスト、またはその他の形式)
   2. ソース トラッキング: uriフィールドは、コンテンツの取得元への参照を保持します。これは次の場合に役立ちます。
      • データの出所を追跡する
      • ソースが変更された場合に更新を有効にする
      • リソースの場所と目的に関するコンテキストを提供する
   3. 構造化データ処理: リソース形式により、各リソースに関するメタデータを維持しながら、さまざまな種類のコンテンツを一貫して処理できます。

   さまざまな役割とコンテンツ タイプを示す例を次に示します。

   "messages": [ { "role": "system", "content": { "type": "text", "text": "Analyze the following log file and code for potential issues." } }, { "role": "user", "content": { "type": "resource", "resource": { "uri": "logs://recent", "text": "[2024-03-14 15:32:11] ERROR: Connection timeout", "mimeType": "text/plain" } } }, { "role": "assistant", "content": { "type": "text", "text": "I notice a connection timeout error. Let me examine the related code." } }, { "role": "user", "content": { "type": "resource", "resource": { "uri": "file:///code.py", "text": "def example():\n pass", "mimeType": "text/x-python" } } } ]

   ほとんどのプロンプトでは、ユーザーロールを付与したテキストタイプで十分であり、Claude は応答をより細かく制御し、創造性を高めることができます。しかし、より複雑なワークフローでは、異なるロールとタイプを持つ複数のメッセージを使用することで、より構造化された会話フローと、ユーザーが応答をより細かく制御できるようになります。

3. プロンプト作成のベストプラクティス
   • プロンプトを焦点を絞って具体的にする
   • 議論には明確な検証要件を含める
   • パラメータにはわかりやすい名前を付ける
   • パラメータの説明にサンプル値を含める
   • クロードを効果的に導くためのプロンプトテンプレートを構成する
   • エラー処理とエッジケースを考慮する
   • さまざまな入力でプロンプトをテストする