GrowSurf MCP サーバー

GrowSurf 公式コマンドラインインターフェース（CLI）およびオープンソースの Model Context Protocol（MCP）サーバーです。GrowSurf リファラル・アフィリエイトプログラムを、ガイド付きステップと安全な REST API ラッパーで実装できます。

AI エージェントに接続すると、自然言語で、リファラル・アフィリエイトプログラムの作成、報酬の設定、トラッキングのインストール、参加者の追加・管理、アナリティクスの閲覧がすべて GrowSurf REST API によって実行できます。

• GrowSurf の詳細: https://growsurf.com

• この MCP サーバーの詳細: https://docs.growsurf.com/build-with-ai

対象者

この MCP サーバーは以下の方を対象としています:

• MCP 互換ツール（Claude Code、Codex、Cursor、Copilot、その他の MCP クライアント）を使用する開発者

• ガイド付きの AI 支援による GrowSurf 統合を希望するチーム

この MCP サーバーは以下の方には不向きです:

• ローカル stdio インストールを希望するブラウザのみのユーザー。ChatGPT web、Claude.ai、Claude Desktop はローカル MCP サーバーを実行しませんが、3 つともホスト型リモートコネクタ https://mcp.growsurf.com を通じて GrowSurf に接続します。完全なクライアントリストとセットアップは https://docs.growsurf.com/build-with-ai#mcp を参照してください。

Related MCP server: SurfRank MCP Server

提供される機能

• ガイド付き統合:

  • ユニバーサルコードのインストール

  • ネイティブ iOS/Android SDK 実装ガイダンス

  • ネイティブ GrowSurf Window ガイダンス

  • サインアップフロー

  • 対象アクションフロー

  • アフィリエイト売上・トランザクショントラッキング

  • Webhook

• エージェントレシピ:

  • リファラルプログラム作成、アフィリエイトプログラム作成、ウィジェット埋め込み、プログラム・参加者の一覧表示と取得、報酬設定、Webhook 配線、アナリティクス閲覧のための MCP プロンプト

  • skills/growsurf-agent-toolkit にあるインストール可能なエージェントスキルバンドル

  • パッチ適用前にスターターの Design、Emails、Options、Installation、報酬、GrowSurf Window コンテンツをレビューするよう誘導

  • スターターコンテンツと設定レビューのためのワンショットプログラム作成評価プロンプトと受け入れチェック

• ハッピーパス REST API ラッパー:

  • 既存の認証情報なしでアカウントを作成し API キーを取得

  • バインドされたチームの読み取り・名前変更、チーム検証のリクエスト、チームオーナーへの検証メールの再送信

  • キャンペーンの一覧表示と取得

  • キャンペーンアナリティクスの取得（合計、オプションの期間別時系列、メール指標、前期間合計、ステータス数、レート）

  • プログラム（キャンペーン）の作成・更新・複製

  • キャンペーン報酬の一覧表示・作成・更新・削除

  • Design、Emails、Options、Installation 設定の取得・更新

  • ユーザーが明示的に視覚的証明を求めた場合の一時的な GrowSurf プレビュースクリーンショットの取得

  • プログラム Webhook の一覧表示・作成・更新・削除・テスト

  • 参加者の一覧表示・取得・追加

  • 参加者の更新、参加者へのメール送信、参加者のアナリティクスとアクティビティログの取得

  • リファラルクレジットのトリガー（リファラルプログラム用）。遅延付与（1〜90 日）もオプションで指定可能

  • 保留中の遅延リファラルトリガーのキャンセル（リファラルプログラム用）

  • アフィリエイト売上・トランザクションの記録（アフィリエイトプログラム用）

  • サインイン済みネイティブアプリユーザー向けモバイル参加者トークンの作成

• 公式 API ライブラリスニペット:

  • TypeScript

  • Python

  • PHP

  • Ruby

  • Java

• ヘルパー:

  • 参加者オート認証 HMAC ハッシュの計算

  • Webhook ペイロードの正規化

  • Webhook 重複排除のためのベストエフォート型冪等キーの生成

要件

• Node.js 22+

• ホスト型 OAuth 用の GrowSurf アカウント

• ローカル stdio セットアップまたは手動 API キーによるリモートセットアップ用の GrowSurf API キー。エージェントに使用させたいツールとプログラムへのアクセス権があれば、スコープ付きキーでも動作します。

• キャンペーンスコープのツール用のキャンペーン（プログラム）ID。GROWSURF_CAMPAIGN_ID をデフォルトとして設定するか、campaignId 引数を渡して特定のプログラムを指定するか、growsurf_list_campaigns を呼び出して利用可能なプログラムを検索します。新しく作成したプログラムの場合は、growsurf_create_campaign が返す id を他のツールに渡します。

• 静的ガイダンス・スニペットツールは認証情報なしで実行可能

• 例外: growsurf_create_account は API キーが不要です。新しいアカウントを作成し API キーを返します。チームレベルのツールにはキャンペーン ID は不要です。

• リストされたすべてのツールは、標準の MCP 読み取り専用・破壊的・冪等・オープンワールド安全性ヒントを公開します。スコープ付きビジネスアクションは引き続き利用可能です。API キーのローテーションは意図的に MCP ツールにしていません。キーのローテーションは GrowSurf 設定または直接の REST/SDK クライアントで行ってください。

公式 CLI

npm パッケージは growsurf-mcp コマンドをインストールします。グローバルインストールなしで実行できます:

npx -y @growsurfteam/growsurf-mcp

CLI は GrowSurf のローカル stdio MCP サーバーを起動します。API を利用したアクションには GROWSURF_API_KEY を、デフォルトのプログラムには GROWSURF_CAMPAIGN_ID を設定してください。公開開発者リソースと静的統合ガイダンスは認証情報なしで動作します。

stdio サーバーを起動せずにインストール済みコマンドを確認するには:

npx -y @growsurfteam/growsurf-mcp --help
npx -y @growsurfteam/growsurf-mcp --version

サポートされている MCP ホスト

推奨パスは、ホストがリモート Streamable HTTP と OAuth をサポートしている場合の GrowSurf ホスト型 OAuth エンドポイント https://mcp.growsurf.com です。ホストが stdio プロセスまたは手動 API キーセットアップを必要とする場合は、ローカルの npx サーバーを使用してください。まだ GrowSurf アカウントをお持ちでない場合、エージェントは認証情報なしでホスト型オンボーディングエンドポイント https://mcp.growsurf.com/onboard に接続し、growsurf_create_account を呼び出してサインアップできます。

GrowSurf MCP サーバーは、MCP 互換の任意のホストで動作します。以下の例は、設定ベースおよび CLI ベースのいくつかのホストをカバーしています。サポートされているクライアントの完全かつ最新のリスト（ChatGPT web、Claude.ai、Claude Desktop、GitHub Copilot、Gemini CLI、Devin Desktop、Cline を含む）とステップバイステップのセットアップについては、https://docs.growsurf.com/build-with-ai#mcp を参照してください。

• Cursor

• Claude Code（CLI ベース）

• Antigravity

• Codex（CLI ベース）

Cursor

1. Cursor のグローバル MCP 設定を ~/.cursor/mcp.json に開くか作成します。

2. ホスト型 OAuth エンドポイントを使用して、growsurf という名前のサーバーを追加します:

{
  "mcpServers": {
    "growsurf": {
      "type": "http",
      "url": "https://mcp.growsurf.com"
    }
  }
}

代わりにローカル stdio を使用する場合:

{
  "mcpServers": {
    "growsurf": {
      "command": "npx",
      "args": ["-y", "@growsurfteam/growsurf-mcp"],
      "env": {
        "GROWSURF_API_KEY": "YOUR_API_KEY",
        "GROWSURF_CAMPAIGN_ID": "YOUR_CAMPAIGN_ID"
      }
    }
  }
}

Claude Code（CLI ベース）

ターミナルを開き、Claude Code をホスト型 OAuth エンドポイントに接続します:

claude mcp add --transport http --scope user growsurf https://mcp.growsurf.com
claude mcp login growsurf

代わりにローカル stdio を使用する場合、サーバーを Claude Code に直接インストールします:

claude mcp add growsurf \
  -e GROWSURF_API_KEY=your_api_key \
  -e GROWSURF_CAMPAIGN_ID=your_campaign_id \
  -- npx -y @growsurfteam/growsurf-mcp

Antigravity

1. Antigravity を開きます。

2. 右側のパネルで … メニューをクリックし、MCP Servers を選択します。

3. Manage MCP Servers > View raw config をクリックします。

4. 推奨: mcp_config.json ファイルにホスト型 OAuth エンドポイントを追加します:

{
  "mcpServers": {
    "growsurf": {
      "serverUrl": "https://mcp.growsurf.com"
    }
  }
}

5. 設定を保存し、Settings > Customizations を開いて、GrowSurf に対して Authenticate を選択します。

代わりにローカル stdio を使用する場合:

{
  "mcpServers": {
    "growsurf": {
      "command": "npx",
      "args": ["-y", "@growsurfteam/growsurf-mcp"],
      "env": {
        "GROWSURF_API_KEY": "YOUR_API_KEY",
        "GROWSURF_CAMPAIGN_ID": "YOUR_CAMPAIGN_ID"
      }
    }
  }
}

Codex

推奨: Codex をホスト型 OAuth エンドポイントに接続します:

codex mcp add growsurf --url https://mcp.growsurf.com
codex mcp login growsurf

または ~/.codex/config.toml を作成・編集します:

[mcp_servers.growsurf]
url = "https://mcp.growsurf.com"

代わりにローカル stdio を使用する場合、以下を追加します:

[mcp_servers.growsurf]
command = "npx"
args = ["-y", "@growsurfteam/growsurf-mcp"]

[mcp_servers.growsurf.env]
GROWSURF_API_KEY = "YOUR_API_KEY"
GROWSURF_CAMPAIGN_ID = "YOUR_CAMPAIGN_ID"

または CLI からローカル stdio を設定します:

codex mcp add growsurf \
  --env GROWSURF_API_KEY=YOUR_API_KEY \
  --env GROWSURF_CAMPAIGN_ID=YOUR_CAMPAIGN_ID \
  -- npx -y @growsurfteam/growsurf-mcp

設定

MCP サーバーを実行する際は、以下の環境変数を設定してください:

• GROWSURF_API_KEY（起動時はオプション。API 呼び出しツールに必須。ツールが必要とするスコープとプログラムアクセスを持つキーを使用）

• GROWSURF_CAMPAIGN_ID（オプション。キャンペーンスコープのツールのデフォルトプログラム。ツールの campaignId 引数がこれを上書きするため、単一のサーバーで任意のプログラムを操作できます）

• GROWSURF_API_BASE_URL（オプション。デフォルトは https://api.growsurf.com/v2。異なる GrowSurf API オリジンを呼び出す必要があるローカルまたはホスト型 MCP ゲートウェイに便利）

• GROWSURF_PARTICIPANT_AUTH_SECRET（オプション。ハッシュヘルパーで使用）

• GROWSURF_WEBHOOK_TOKEN（オプション。独自の Webhook URL トークンスキームで使用）

npx で実行

このパッケージの公開後、顧客は以下を実行できます:

npx @growsurfteam/growsurf-mcp

このリポジトリでのローカル開発の場合:

npm install
npm run build
node dist/cli.js

MCP ツール

すべてのツールは MCP 出力スキーマを宣言し、structuredContent を返すため、ホストは各ツールの結果の形状を認識できます。REST ツールは API レスポンスを返し（古いクライアント用の JSON テキストブロックも含む）、ガイダンス・スニペットツールは markdown の下にマークダウンドキュメントを返します。

ガイド付き統合

• growsurf_integration_guide GrowSurf リファラル・アフィリエイトプログラムを実装するためのステップバイステップのガイダンス。

• growsurf_mobile_sdk_guide アトリビューション、shareUrl、trackShare、ネイティブ GrowSurf Window のためのネイティブ iOS/Android SDK ガイダンス。

• growsurf_api_library_snippets TypeScript、Python、PHP、Ruby、Java 向けの公式 REST API ライブラリスニペット。

• growsurf_get_integration_connect_link 特定の統合の接続パネル（Stripe、PayPal、Tango Card、Mailchimp など）を開くダッシュボードリンクを取得します。ユーザーが接続したいときに渡します。接続は API ではなくダッシュボードで行われます。

クライアント・UI スニペット

• growsurf_client_snippets JavaScript SDK、GrowSurf Window、埋め込み可能な例。埋め込み可能な UI を配置・スタイリングする際にフロントエンドデザインワークフローを使用するよう促すリマインダーを含みます。

• growsurf_embeddable_element_snippet 特定の GrowSurf 埋め込み可能要素の HTML スニペット。

• growsurf_grsf_config_snippet window.grsfConfig と参加者オート認証を設定するための <head> スニペット。

アカウントオンボーディング

• growsurf_create_account GrowSurf アカウントを作成し API キーを取得します。GROWSURF_API_KEY を必要としない唯一のツールです。返されたキーは一度だけ表示され、オーナーがメールを検証するまでロックされます（403 EMAIL_NOT_VERIFIED_ERROR）。キーはオーナーが初めてダッシュボードにサインインしたときにローテーションされます。アカウントを作成すると、アカウント所有者に代わって GrowSurf の利用規約とプライバシーポリシーに同意したことになります。

チーム

• growsurf_get_team API キーまたは OAuth 接続にバインドされたチームを、GrowSurf 検証状態を含めて取得します。

• growsurf_update_team バインドされたチームの表示名を更新します。

• growsurf_request_team_verification GrowSurf にバインドされたチームの検証をリクエストします。プログラムが参加者にメールを送信する前に必要です。

• growsurf_resend_team_owner_verification_email バインドされたチームのオーナーのメールアドレスを明かさずに、検証メールを再送信します。

API とトラッキング

• growsurf_get_campaign キャンペーン設定を取得します。

• growsurf_list_campaigns 認証情報で利用可能なプログラムを一覧表示します。キャンペーン単位のツールを呼び出す前に、これを使用して campaignId を検索します。

• growsurf_get_campaign_analytics プログラムの分析情報を取得します。オプションで期間ごとの series、比較、ステータス、レート、include=email によるメール配信・エンゲージメントデータを含めることができます。

• growsurf_create_campaign タイプに応じたスターターコンテンツとオプションのインライン報酬を備えた新しいプログラム（キャンペーン）を作成します（GROWSURF_CAMPAIGN_ID ではなく GROWSURF_API_KEY のみが必要です）。パッチ適用前に、シードされたデザイン、メール、オプション、インストール、報酬、GrowSurf ウィンドウのコンテンツを確認してください。

• growsurf_agent_program_creation_eval スターターコンテンツ、控えめな報酬、設定レビュー、フロントエンドインストールの証明、クリーンな公開コピーに対するワンショットのプログラム作成評価プロンプトと受け入れチェックを生成します。

• growsurf_update_campaign プログラムの識別情報とライフサイクル（名前、会社ブランディング、ステータス）を更新します（送信したフィールドのみが変更されます）。

• growsurf_clone_campaign プログラムを新しい DRAFT プログラムに複製します（統合と認証情報はコピーされません）。

• growsurf_list_campaign_rewards プログラムに設定された報酬を一覧表示します。

• growsurf_create_campaign_reward キャンペーン報酬を作成します。

• growsurf_update_campaign_reward 報酬キーでキャンペーン報酬を更新します。

• growsurf_delete_campaign_reward 報酬キーでキャンペーン報酬を削除します。

• growsurf_get_campaign_design / growsurf_update_campaign_design デザイン設定（Program Editor の Design タブと支払い先確認ページのコピーを含む）を読み取りまたはパッチ適用します。

• growsurf_get_campaign_emails / growsurf_update_campaign_emails Program Editor の Emails タブ設定を読み取りまたはパッチ適用します。

• growsurf_get_campaign_options / growsurf_update_campaign_options Program Editor の Options タブ設定を読み取りまたはパッチ適用します。

• growsurf_get_campaign_installation / growsurf_update_campaign_installation Program Editor の Installation タブ設定を読み取りまたはパッチ適用します。

• growsurf_capture_referral_flow_screenshots ユーザーが明示的に視覚的な証明を求めた後、現在のプログラムの一時的な GrowSurf プレビュースクリーンショットを取得します。これは管理された紹介者ウィンドウと紹介された友人の体験を返します。ユーザーのインストール済みサイトを証明するには、代わりにブラウザ自動化を使用してください。

• growsurf_list_campaign_webhooks プログラムのウェブフックを一覧表示します（シークレットは決して返されません）。

• growsurf_create_campaign_webhook プログラムにウェブフックを追加します（イベントと書き込み専用の署名シークレット付き）。

• growsurf_update_campaign_webhook ID でウェブフックを更新します（プログラムのプライマリウェブフックには primary を使用）。

• growsurf_delete_campaign_webhook ID でウェブフックを削除します。

• growsurf_test_campaign_webhook 保存された URL とシークレットを使用して、ウェブフックにライブテストイベントを送信します。

• growsurf_add_participant サインアップ時に参加者（または紹介された参加者）を追加します。

• growsurf_list_participants 現在のプログラムの参加者を nextId でページングして一覧表示します。参加者単位のツールを呼び出す前に、これを使用して参加者 ID を検索します。

• growsurf_get_participant GrowSurf の参加者 ID またはメールアドレスで 1 人の参加者を取得します。

• growsurf_update_participant ID またはメールアドレスで参加者を更新します（内部 notes を含む）。

• growsurf_bulk_delete_participants 1 回のリクエストで最大 200 人の参加者を（ID および/またはメールアドレスで、混合リストも可）完全に削除します。行ごとに DELETED/NOT_FOUND/DUPLICATE/ERROR の結果が返ります。元に戻せません — 参加者の紹介、報酬、コミッション、支払い記録が削除されます。

• growsurf_email_participant 設定済みテンプレートまたは自由形式の件名/本文を使用して参加者にメールを送信します。

• growsurf_get_participant_analytics 1 人の参加者のエンゲージメント、ランク、シェア、アフィリエイト収益、コミッション、支払い、およびオプションのメール指標を取得します。include=series、include=email、または両方をカンマ区切りで使用します。

• growsurf_get_participant_activity_logs 参加者のアクティビティログを一覧表示します（オフセット/リミットでページング）。

• growsurf_trigger_referral 紹介をトリガーします（紹介プログラムのみ）。オプションで delayInDays（1〜90）を渡すと、報酬を付与する前に N 日間クレジットを保留できます（例：返金期間をカバーするため）。

• growsurf_cancel_delayed_referral 遅延期間が経過する前に、保留中の遅延紹介トリガーをキャンセルします（例：返金/キャンセル時）。

• growsurf_get_participant_payout_destination プログラムで有効なすべてのプロバイダー（PayPal および/または Wise）における参加者の支払い先ステータスを取得します：プロバイダーごとのステータス、確認済みの支払いメール、法的な受取人タイプ、修正理由。

• growsurf_request_participant_payout_destination_confirmation 参加者にプロバイダーの支払い先の確認を依頼します — ワンタイム確認リンクが送信されます（確認できるのは参加者のみです）。

• growsurf_record_sale アフィリエイトの売上または取引を記録します（アフィリエイトプログラムのみ）。

• growsurf_refund_transaction 記録された取引に対する修正（返金、部分返金、またはチャージバック）を記録します。紹介者のコミッションを反転または調整します（アフィリエイトプログラムのみ）。growsurf_record_sale の逆操作です。

• growsurf_create_mobile_participant_token 参加者を作成または取得し、サインイン済みモバイルユーザー向けの参加者スコープのモバイル SDK トークンを作成します。

ヘルパー

• growsurf_participant_auth_hash 参加者の自動認証 HMAC ハッシュを生成します（参加者を自動的に認証するため）。

• growsurf_webhook_normalize ウェブフックのペイロードを正規化し、冪等性キーを生成します（ウェブフック配信の重複排除のため）。

ウェブフック

GrowSurf のウェブフックは、参加者、紹介、報酬、取引などの新しいオブジェクトが作成されたときなど、重要な紹介またはアフィリエイトイベントが発生したときにサーバーに通知します。一般的なユースケースは次のとおりです：

• 報酬を自動的に履行する

• 内部のポイントまたはクレジットシステムを維持する

• 参加者と紹介データをデータベースに同期する

重複配信の処理

同じイベントが複数回届く可能性があるため、ウェブフックハンドラーは冪等である必要があります。システム内で何かを変更する前に、冪等性キーを保存してください。

ウェブフックのセキュリティと冪等性

ウェブフックに secret が設定されている場合、GrowSurf はウェブフック配信に署名します。各配信には、そのシークレットで計算された GrowSurf-Signature HMAC ヘッダーが含まれます（シークレットは書き込み専用で、決して返されません）。ウェブフックを安全に使用するには、以下を推奨します：

• ウェブフックに secret を設定し、受信時に GrowSurf-Signature ヘッダーを検証する

• ペイロードの形状と期待されるイベントタイプを検証する

• 同じイベントが複数回届く可能性があるため、冪等性キーを使用してウェブフックイベントの重複を排除する

GrowSurf MCP サーバーは、ウェブフックのペイロードを正規化し、ベストエフォートの冪等性キーを生成して安全なウェブフック処理を簡素化するヘルパーツール（growsurf_webhook_normalize）を提供します。

開発とテスト

npm run dev
npm test

追加リソース

以下の開発者ドキュメントをお読みください：

• JavaScript SDK リファレンス：https://docs.growsurf.com/developer-tools/javascript-sdk/api-reference

• REST API リファレンス：https://docs.growsurf.com/developer-tools/rest-api/api-reference

• REST API ライブラリ：https://docs.growsurf.com/developer-tools/rest-api/api-libraries

• ネイティブモバイルガイド：https://docs.growsurf.com/getting-started-for-native-mobile

• iOS SDK：https://docs.growsurf.com/developer-tools/ios-sdk

• Android SDK：https://docs.growsurf.com/developer-tools/android-sdk

• GrowSurf 入門：https://docs.growsurf.com/getting-started

GrowSurf MCP サーバーは、GrowSurf のお客様が紹介プログラムとアフィリエイトプログラムを迅速に実装できるように支援します。