Umami Analytics MCP Server

Umami Analytics MCP サーバー

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

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

このサーバーの機能

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

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

仕組み

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

利用可能なツール

• 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 のオープンソースの sentence transformer モデルを使って埋め込みます。そして質問に基づいて最も関連性の高いチャンクを取得し、Claude に返すことで、ウェブサイト上でユーザーが行った特定の操作や行動を分析できます。これは従来のデータ可視化ツールでは再現が難しい機能です。埋め込みとセマンティック検索の実装は、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 の設定

   次の内容を 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を開く

Claude Desktopを開くと、自動的にanalytics_service MCPサーバーへの接続が始まります。サーバーの初期化と必要なパッケージのインストールが完了するまで、数分ほどお待ちください。サーバーの準備ができると、チャットウィンドウの右下に10個のMCPツールが表示されます。小さなハンマーアイコンの横に数字の10が表示されます。

また、まだ有効にしていない場合は、Claude DesktopのFeature Previewで「Analysis tool」を有効にすることを強くおすすめします。これにより、Claudeがデータのダッシュボードやその他のビジュアライゼーションを作成できるようになります。有効にするには、左側のパネルで「Feature Preview」タブを見つけ、その中の「Analysis tool」を有効にしてください。同じセクションでLaTeX Renderingも有効にできます。

サーバーの使い方

はじめに

最も簡単な始め方は、サーバーが提供するCreate Dashboard Promptを使用することです。チャットウィンドウの左下にある「Attach from MCP」添付ボタンをクリックし、「choose implementation」を選択してから「Create Dashboard Prompt」を選択します。

これにより、次の情報を確認しながら、Webサイトのダッシュボードを作成する手順が案内されます。

1. 分析するWebサイトの名前
2. 分析の開始日と終了日
3. Webサイトのタイムゾーン

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

自然言語での使用

より柔軟に利用するには、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" を使用します
   • Claude の応答や指示を表すメッセージには "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"
               }
           }
       }
   ]
   

   ほとんどのプロンプトでは、user ロールの text タイプで十分であり、Claude が応答をより自由に創造的に生成できます。ただし、より複雑なワークフローでは、異なるロールとタイプを使った複数のメッセージによって、より構造化された会話の流れを実現し、応答をより細かく制御できます。

3. プロンプト作成のベストプラクティス

   • プロンプトは目的を絞り、具体的にします
   • 引数に対する明確な検証要件を含めます
   • パラメーターには説明的な名前を使用します
   • パラメーターの説明に値の例を含めます
   • Claude を効果的に導けるよう、プロンプトテンプレートを構成します
   • エラー処理とエッジケースを考慮します
   • さまざまな入力を使ってプロンプトをテストします