Goatcounter MCP Server

Goatcounter MCP サーバー

概要

このプロジェクトは、Goatcounter ウェブ分析 API と連携するための Model Context Protocol（MCP）サーバーを提供します。標準化されたツールインターフェースを使用して、LLM やその他の MCP クライアントが Goatcounter の統計情報や情報を簡単にクエリできます。

このサーバーは Python と FastMCP ライブラリを使用して構築されています。認証には、環境変数から Goatcounter のサイトコードと API キーを読み込みます。

機能

• Goatcounter API のほとんどのエンドポイントに対応するツールを提供します。
• 環境変数（GOATCOUNTER_API_KEY、GOATCOUNTER_CODE）を使用して API キーとサイトコードを設定します。
• API クライアントを遅延初期化します。API 認証情報がまだ設定されていなくても、ツールを一覧表示できます。
• レート制限への対応：API のレート制限（HTTP 429）に遭遇した場合、バックオフを伴う自動再試行を実装しています。
  • API から提供される場合は、待機時間の決定に X-Rate-Limit-Reset ヘッダーを優先して使用します。
  • ヘッダーが利用できないか無効な場合は、ランダムなジッターを加えた指数バックオフ（1 秒から開始）に切り替えます。
  • 失敗するまで最大 5 回再試行します。
• fastmcp コマンドラインツールを使って直接実行できます。

インストール

オプション 1：Smithery 経由でインストール（推奨）

Smithery 経由で X（Twitter）MCP サーバーを Claude Desktop に自動でインストールするには：

npx -y @smithery/cli install @rafaljanicki/goatcounter-mcp-server --client claude

オプション 2：PyPI からインストール

goatcounter-mcp-server をインストールする最も簡単な方法は、PyPI を使用することです。

pip install goatcounter-mcp-server

または、リポジトリから直接インストールします。

pip install git+https://github.com/rafaljanicki/goatcounter-mcp-server.git

オプション 3：ソースからインストール

ソースリポジトリからインストールする場合：

1. リポジトリをクローンします：

   git clone https://github.com/rafaljanicki/goatcounter-mcp-server
   cd goatcounter-mcp-server
   

2. 仮想環境を作成します：

   python3.13 -m venv venv
   source venv/bin/activate  # Windows では `venv\Scripts\activate` を使用します
   

3. 依存関係をインストールします： FastMCP とその他の必要なパッケージをインストールします。

   pip install -r requirements.txt
   

4. 環境変数を設定します： サンプルの .env.example ファイルを .env にコピーします。

   cp .env.example .env
   

   .env ファイルを編集し、Goatcounter の情報を追加します（下記の「環境変数」セクションを参照）。

環境変数

サーバーを使用するには、次の環境変数を設定する必要があります。

• GOATCOUNTER_CODE：Goatcounter のサイトコード（サブドメイン部分。例：'mycoolsite'）。
• GOATCOUNTER_API_KEY：Goatcounter の API トークン。Goatcounter サイトの「Settings -> API tokens」で生成できます。使用する API アクションに必要な権限が付与されていることを確認してください。

これらの変数は環境に直接設定するか、プロジェクトのルートにある .env ファイルに記述できます。

サーバーの実行

オプション 1：CLI スクリプトを使用する

このプロジェクトでは、CLI スクリプト goatcounter-mcp-server を定義しています。

PyPI からインストールした場合：

goatcounter-mcp-server

uv を使用してソースからインストールした場合：

uv run goatcounter-mcp-server

オプション 2：FastMCP を直接使用する（ソースのみ）

ソースからインストールし、FastMCP の開発モードでサーバーを実行する場合：

fastmcp dev src/goatcounter_mcp_server/server.py

Claude Desktop での使用

この MCP サーバーを Claude Desktop で使用するには、サーバーに接続するよう Claude を設定する必要があります。次の手順に従ってください。

ステップ 1：Node.js をインストールする

Claude Desktop は MCP サーバーの実行に Node.js を使用します。Node.js がインストールされていない場合：

• nodejs.org から Node.js をダウンロードしてインストールします。
• インストールを確認します。

  node --version
  

ステップ 2：Claude Desktop の設定ファイルを確認する

Claude Desktop は、MCP サーバーの設定に claude_desktop_config.json ファイルを使用します。

• Windows：%APPDATA%\Claude\claude_desktop_config.json
• macOS：~/Library/Application Support/Claude/claude_desktop_config.json

ファイルが存在しない場合は、作成してください。

ステップ 3：MCP サーバーを設定する

claude_desktop_config.json を編集して、goatcounter-mcp-server サーバーを追加します。/path/to/goatcounter-mcp-server を、プロジェクトディレクトリの実際のパス（ソースからインストールした場合）または Python 実行ファイルのパス（PyPI からインストールした場合）に置き換えてください。

PyPI からインストールした場合：

{
  "mcpServers": {
    "goatcounter-mcp-server": {
      "command": "goatcounter-mcp-server",
      "args": [],
      "env": {
        "PYTHONUNBUFFERED": "1",
        "GOATCOUNTER_CODE": "goatcounter_code",
        "GOATCOUNTER_API_KEY": "goatcounter_api_key"
      }
    }
  }
}

uv を使ってソースからインストールした場合：

{
  "mcpServers": {
    "goatcounter-mcp-server": {
      "command": "uv",
      "args": [
        "--directory",
        "/path/to/goatcounter-mcp-server",
        "run",
        "goatcounter-mcp-server"
      ],
      "env": {
        "PYTHONUNBUFFERED": "1",
        "GOATCOUNTER_CODE": "goatcounter_code",
        "GOATCOUNTER_API_KEY": "goatcounter_api_key"
      }
    }
  }
}

• "command": "goatcounter-mcp-server"：PyPI からインストールした場合、CLI スクリプトを直接使用します。
• "env"：PyPI からインストールした場合、環境変数を設定ファイルに直接指定する必要がある場合があります（.env ファイルがないためです）。ソースからインストールした場合は、.env ファイルが使用されます。
• "env": {"PYTHONUNBUFFERED": "1"}：Claude でのログ記録を改善するため、出力をバッファーなしにします。

ステップ 4：Claude Desktop を再起動する

• Claude Desktop を完全に終了します。
• Claude Desktop を再度開いて、新しい設定を読み込みます。

ステップ 5：接続を確認する

• Claude Desktop を開きます。
• 入力エリアの右下隅にあるハンマーまたはコネクターのアイコンを確認します。これは、MCP ツールが利用可能であることを示します。
• アイコンをクリックすると、goatcounter-mcp-server で利用できるツールが表示されます。

API ドキュメント：利用可能なツール

以下の MCP ツールを利用できます。

---

ツール：Goatcounter_get_me

現在の Goatcounter ユーザーと、設定されている GOATCOUNTER_API_KEY に関連付けられた API キーの情報を取得します。

• パラメーター：なし
• 戻り値：object - ユーザーとトークンに関する情報。

---

ツール：Goatcounter_list_sites

現在の API キーでアクセスできるすべての Goatcounter サイトを一覧表示します。

• パラメーター：なし
• 戻り値：object - アクセス可能なサイトの一覧。

---

ツール：Goatcounter_list_paths

このサイトで追跡されているパスの概要を取得します（統計情報は含みません）。

• パラメーター：
  • limit（整数、任意）：返される結果の数を制限します（1～200、デフォルトは 20）。
  • after（整数、任意）：ページネーション用に、このパス ID より後のパスのみを選択します。
• 戻り値：object - パスの一覧とページネーション情報。

---

ツール：Goatcounter_get_stats_total

指定した期間における、サイトの合計ページビュー数とユニーク訪問者数を取得します。

• パラメーター：
  • start（文字列、任意）：開始日（YYYY-MM-DD または「7 days ago」のような相対指定）。
  • end（文字列、任意）：終了日（YYYY-MM-DD または「yesterday」のような相対指定）。
  • filter（文字列、任意）：パスで絞り込みます（例：'/blog*'）。
  • daily（ブール値、任意）：合計ではなく日ごとの統計を表示します（デフォルト：false）。
• 戻り値：object - 合計統計、または daily が true の場合は日ごとの統計。

---

ツール：Goatcounter_get_stats_hits

ページ統計（パスごとのページビュー数と訪問者数）を一覧表示します。

• パラメーター：
  • start（文字列、任意）：開始日（YYYY-MM-DD または「7 days ago」のような相対指定）。
  • end（文字列、任意）：終了日（YYYY-MM-DD または「yesterday」のような相対指定）。
  • filter（文字列、任意）：パスで絞り込みます（例：'/blog*'）。
  • daily（ブール値、任意）：合計ではなく日ごとの統計を表示します（デフォルト：false）。
  • limit（整数、任意）：返される結果の数を制限します（1～200、デフォルトは 20）。
  • after（整数、任意）：ページネーションカーソル。
• 戻り値：object - パスごとの統計の一覧とページネーション情報。

---

ツール：Goatcounter_get_stats_refs

リファラー統計を一覧表示します。

• パラメーター：
  • start（文字列、任意）：開始日（YYYY-MM-DD、または「7 days ago」などの相対日付）。
  • end（文字列、任意）：終了日（YYYY-MM-DD、または「yesterday」などの相対日付）。
  • filter（文字列、任意）：パスを絞り込みます（例：/blog*）。
  • daily（ブール値、任意）：合計ではなく日別の統計を表示します（デフォルト：false）。
  • limit（整数、任意）：返す結果の数を制限します（1～200、デフォルト：20）。
  • after（整数、任意）：ページネーションカーソル。
• 戻り値：object - リファラー統計の一覧とページネーション情報。

---

ツール：Goatcounter_get_stats_browsers

ブラウザー統計を一覧表示します。

• パラメーター：
  • start（文字列、任意）：開始日（YYYY-MM-DD、または「7 days ago」などの相対日付）。
  • end（文字列、任意）：終了日（YYYY-MM-DD、または「yesterday」などの相対日付）。
  • filter（文字列、任意）：パスを絞り込みます（例：/blog*）。
  • daily（ブール値、任意）：合計ではなく日別の統計を表示します（デフォルト：false）。
  • limit（整数、任意）：返す結果の数を制限します（1～200、デフォルト：20）。
  • after（整数、任意）：ページネーションカーソル。
• 戻り値：object - ブラウザー統計の一覧とページネーション情報。

---

ツール：Goatcounter_get_stats_systems

オペレーティングシステム統計を一覧表示します。

• パラメーター：
  • start（文字列、任意）：開始日（YYYY-MM-DD、または「7 days ago」などの相対日付）。
  • end（文字列、任意）：終了日（YYYY-MM-DD、または「yesterday」などの相対日付）。
  • filter（文字列、任意）：パスを絞り込みます（例：/blog*）。
  • daily（ブール値、任意）：合計ではなく日別の統計を表示します（デフォルト：false）。
  • limit（整数、任意）：返す結果の数を制限します（1～200、デフォルト：20）。
  • after（整数、任意）：ページネーションカーソル。
• 戻り値：object - OS 統計の一覧とページネーション情報。

---

ツール：Goatcounter_get_stats_sizes

画面サイズ統計を一覧表示します。

• パラメーター：
  • start（文字列、任意）：開始日（YYYY-MM-DD、または「7 days ago」などの相対日付）。
  • end（文字列、任意）：終了日（YYYY-MM-DD、または「yesterday」などの相対日付）。
  • filter（文字列、任意）：パスを絞り込みます（例：/blog*）。
  • daily（ブール値、任意）：合計ではなく日別の統計を表示します（デフォルト：false）。
  • limit（整数、任意）：返す結果の数を制限します（1～200、デフォルト：20）。
  • after（整数、任意）：ページネーションカーソル。
• 戻り値：object - 画面サイズ統計の一覧とページネーション情報。

---

ツール：Goatcounter_get_stats_locations

地域統計を一覧表示します。

• パラメーター：
  • start（文字列、任意）：開始日（YYYY-MM-DD、または「7 days ago」などの相対日付）。
  • end（文字列、任意）：終了日（YYYY-MM-DD、または「yesterday」などの相対日付）。
  • filter（文字列、任意）：パスを絞り込みます（例：/blog*）。
  • daily（ブール値、任意）：合計ではなく日別の統計を表示します（デフォルト：false）。
  • limit（整数、任意）：返す結果の数を制限します（1～200、デフォルト：20）。
  • after（整数、任意）：ページネーションカーソル。
• 戻り値：object - 地域統計の一覧とページネーション情報。

使用方法

1. 環境変数を設定する： プロジェクトのルートに.envファイルを作成するか、環境変数を直接設定します：

   GOATCOUNTER_CODE=your_site_code
   GOATCOUNTER_API_KEY=your_goatcounter_api_key
   

   Goatcounter アカウントの設定で API キーを生成できます。

2. FastMCP で実行する： このサーバーを FastMCP のセットアップに統合します。MCP サーバーの接続方法については、FastMCP のドキュメントを参照してください。

   サーバーはGoatcounterというプレフィックスのツールを登録します（例：Goatcounter.list_sites）。

開発

• 開発用の依存関係をインストールします：pip install -e ".[dev]"（開発用の依存関係が pyproject.toml で指定されている場合）
• このプロジェクトではビルドに hatch を使用しています。

貢献

貢献を歓迎します！Issue を作成するか、プルリクエストを送信してください。

ライセンス

このプロジェクトは MIT License の下でライセンスされています。詳細は LICENSE ファイルをご覧ください。