MCP Pirsch

Pirsch MCP サーバー

Model Context Protocol に対応した、Pirsch Analytics API v1 専用の読み取り専用サーバーです。MCP SDK v2 を使用し、成功したすべてのツール呼び出しに対して、構造化された結果と JSON テキストの両方を返します。

必要条件

• Node.js 22.19.0 以降
• 読み取りアクセス権を持つ Pirsch OAuth API クライアント。書き込み専用のアクセスキーは使用しないでください。

設定

{
  "mcpServers": {
    "pirsch": {
      "command": "npx",
      "args": ["-y", "@verygoodplugins/mcp-pirsch@latest"],
      "env": {
        "PIRSCH_CLIENT_ID": "your-read-only-oauth-client-id",
        "PIRSCH_CLIENT_SECRET": "your-oauth-client-secret",
        "PIRSCH_DEFAULT_DOMAIN_ID": "optional-default-domain-id"
      }
    }
  }
}

PIRSCH_DEFAULT_DOMAIN_ID は任意です。設定されていない場合、すべてのクエリツールで domainId が必須となります。サーバーが最初にアクセス可能なドメインを選択することはありません。ID を安全に確認するには pirsch_list_domains を使用してください。

任意の PIRSCH_TIMEZONE を設定すると、リクエストで timezone が明示されていない場合のデフォルトのタイムゾーンになります。

ツール

ツール	目的
pirsch_list_domains	id、ホスト名、表示名、タイムゾーンのみを一覧表示します。
pirsch_query_statistics	日付とフィルターを指定して、文書化された v1 指標を 1 つ取得します。
pirsch_list_filter_options	文書化されたフィルター項目で使用できる値を一覧表示します。
pirsch_compare_periods	2 つの期間の実際の合計値と訪問者の系列を比較します。

すべてのツールは読み取り専用です。出力スキーマに一致する structuredContent と、それと同等の JSON テキストブロックを返します。入力または API のエラーでは MCP の isError: true が返され、認証情報や上流からの生のレスポンス本文が公開されることはありません。

統計のクエリ

pirsch_query_statistics では metric、任意の domainId、およびフラットなキャメルケースのフィルターを指定できます。ほとんどの指標では ISO 日付が必要です。

{
  "metric": "pages",
  "domainId": "your-domain-id",
  "from": "2026-08-01",
  "to": "2026-08-23",
  "limit": 20,
  "sort": "visitors",
  "direction": "desc"
}

サーバーは eventMetaKey、entryPath、operatingSystem、utmCampaign などの公開キャメルケースフィールドを、Pirsch の文書化された API v1 パラメーター名に対応付けます。limit は 1～100、アクティブな訪問者の start は 0～3600 秒に制限されます。

指標には、合計、訪問者、ページとランディング／離脱ページ、セッションとページの滞在時間、目標、イベントとイベントメタデータ、成長、アクティブな訪問者、時間別の内訳、流入、ブラウザー／デバイス、地域、UTM、タグ、キーワード、ファネル、セッション、セッション詳細が含まれます。session_details では visitorId と sessionId の両方が必要です。イベント固有の指標では event が必要です。

期間の比較

名前付きの period（today、yesterday、week、lastWeek、month、lastMonth）を指定するか、日付のペアを 2 組とも明示してください。

{
  "domainId": "your-domain-id",
  "from": "2026-08-01",
  "to": "2026-08-07",
  "compareFrom": "2026-07-25",
  "compareTo": "2026-07-31",
  "scale": "day"
}

レスポンスでは /statistics/total が比較され、2 つの /statistics/visitor 系列が保持されます。グラフの合計値から推定して合計値を算出することはありません。

1.0 への移行

バージョン 1.0 では、従来の 17 個のツールインターフェイスを意図的に置き換えています。エイリアスは、安全でないドメイン選択や曖昧な入力の動作を温存してしまうため、デフォルトでは用意されていません。

以前のツール	置き換え先
pirsch_overview、pirsch_total、pirsch_pages、pirsch_events、その他の統計ツール	metric を指定した pirsch_query_statistics
pirsch_utm	いずれかの utm_* 指標を指定した pirsch_query_statistics
pirsch_compare	pirsch_compare_periods
ドメインの検索	pirsch_list_domains

入力名はキャメルケースでフラットになりました（domainId、compareFrom、eventMetaKey）。domain_id、ネストされた filter、互換性エイリアスは使用しません。

開発

npm install
npm run typecheck
npm run lint
npm test
npm run build
npx -y @modelcontextprotocol/inspector@latest --cli node dist/index.js --method tools/list --format json

リリースワークフローでは、トラステッドパブリッシングを使用して npm に公開した後、GitHub OIDC を通じて同じタグ付きマニフェストを MCP Registry に公開します。ローカル開発と CI では公開処理は行われません。

サポート

バグや機能リクエストについては、このリポジトリで issue を作成してください。Pirsch に関する質問には Pirsch のドキュメント が最適です。パッケージのサポートは Very Good Plugins が提供しています。

Very Good Plugins が 🧡 を込めて開発しました。