GrowSurf MCP 服务器

官方 GrowSurf 命令行界面（CLI）和开源模型上下文协议（MCP）服务器，用于通过引导式步骤和安全 REST API 包装器实现 GrowSurf 推荐和联盟计划。

将其连接到 AI 代理，用自然语言，代理即可创建推荐或联盟计划、配置奖励、安装跟踪、添加和管理参与者、读取分析数据，全部由 GrowSurf REST API 支持。

• 在 https://growsurf.com 了解更多关于 GrowSurf 的信息

• 在 https://docs.growsurf.com/build-with-ai 了解更多关于此 MCP 服务器的信息

适用对象

此 MCP 服务器适用于：

• 使用 MCP 兼容工具（Claude Code、Codex、Cursor、Copilot 和其他 MCP 客户端）的开发者

• 希望获得引导式、AI 辅助的 GrowSurf 集成的团队

此 MCP 服务器不适用于：

• 仅使用浏览器、希望本地 stdio 安装的用户。ChatGPT 网页版、Claude.ai 和 Claude Desktop 不运行本地 MCP 服务器，但三者都通过托管远程连接器 https://mcp.growsurf.com 连接到 GrowSurf。请参阅 https://docs.growsurf.com/build-with-ai#mcp 获取完整客户端列表和设置。

Related MCP server: SurfRank MCP Server

您将获得

• 引导式集成：

  • 通用代码安装

  • 原生 iOS/Android SDK 实施指南

  • 原生 GrowSurf 窗口指南

  • 注册流程

  • 合格操作流程

  • 联盟销售/交易跟踪

  • Webhooks

• 代理配方：

  • 用于创建推荐计划、创建联盟计划、嵌入小部件、列出和获取计划与参与者、配置奖励、连接 webhooks 以及读取分析数据的 MCP 提示

  • 可安装的代理技能包，位于 skills/growsurf-agent-toolkit

  • 引导审查入门设计、电子邮件、选项、安装、奖励和 GrowSurf 窗口内容后再进行修补

  • 一次性计划创建评估提示和验收检查，用于审查入门内容和配置

• 快乐路径 REST API 包装器：

  • 无需现有凭据即可创建账户并获取 API 密钥

  • 读取和重命名绑定的团队，请求团队验证，并重新发送团队所有者的验证电子邮件

  • 列出和获取活动

  • 获取活动分析（总计、可选的按周期时间序列、电子邮件指标、上一周期总计、状态计数和比率）

  • 创建、更新和克隆计划（活动）

  • 列出、创建、更新和删除活动奖励

  • 获取/更新设计、电子邮件、选项和安装配置

  • 当用户明确要求视觉证明时，捕获临时的 GrowSurf 预览截图

  • 列出、创建、更新、删除和测试计划 webhooks

  • 列出、获取和添加参与者

  • 更新参与者、向参与者发送电子邮件，并获取参与者的分析和活动日志

  • 触发推荐积分（适用于推荐计划），可选择延迟奖励（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 网页版、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. 添加一个名为 growsurf 的服务器，使用托管 OAuth 端点：

{
  "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 下返回其 markdown 文档。

引导式集成

• growsurf_integration_guide 实施 GrowSurf 推荐或联盟计划的逐步指南。

• growsurf_mobile_sdk_guide 原生 iOS/Android SDK 指南，涵盖归因、shareUrl、trackShare 和原生 GrowSurf 窗口。

• 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 窗口和可嵌入示例。包括在放置或样式化可嵌入 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_API_KEY，无需 GROWSURF_CAMPAIGN_ID）。在修补之前，请先审查预置的 Design、Emails、Options、Installation、奖励和 GrowSurf Window 内容。

• 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 预览截图。此工具返回受控的推荐人 Window 和被推荐好友体验；请改用浏览器自动化来证明用户已安装的网站。

• growsurf_list_campaign_webhooks 列出项目的 webhook（密钥永远不会返回）。

• growsurf_create_campaign_webhook 向项目添加 webhook（包含事件和只写的签名密钥）。

• growsurf_update_campaign_webhook 按 id 更新 webhook（primary 表示项目的主 webhook）。

• growsurf_delete_campaign_webhook 按 id 移除 webhook。

• growsurf_test_campaign_webhook 使用存储的 URL 和密钥向 webhook 发送实时测试事件。

• growsurf_add_participant 在注册期间添加参与者（或被推荐的参与者）。

• growsurf_list_participants 列出当前项目中的参与者，通过 nextId 分页。在调用参与者级工具之前，请使用此工具查找参与者 ID。

• growsurf_get_participant 按 GrowSurf 参与者 ID 或电子邮件地址获取单个参与者。

• growsurf_update_participant 按 ID 或电子邮件更新参与者（包括内部 notes）。

• growsurf_bulk_delete_participants 在一次请求中永久删除最多 200 个参与者（按 ID 和/或电子邮件，允许混合列表），每行返回 DELETED/NOT_FOUND/DUPLICATE/ERROR 结果。此操作不可逆——将删除参与者的推荐、奖励、佣金和付款记录。

• growsurf_email_participant 使用已配置的模板或自由格式的主题/正文向参与者发送电子邮件。

• growsurf_get_participant_analytics 获取单个参与者的参与度、排名、分享、联盟收入、佣金、付款以及可选的邮件指标。使用 include=series、include=email 或两者以逗号分隔组合使用。

• growsurf_get_participant_activity_logs 列出参与者的活动日志（offset/limit 分页）。

• 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 规范化 webhook 负载并生成幂等键（用于对 webhook 投递去重）。

Webhooks

当重要的推荐或联盟事件发生时（例如创建参与者、推荐、奖励或交易等新对象时），GrowSurf webhook 会通知您的服务器。以下是常见用例：

• 自动履行奖励

• 维护内部积分或信用系统

• 将参与者和推荐数据同步到您的数据库

重复投递处理

Webhook 处理器应具备幂等性，因为同一事件可能到达多次。在更改系统中的任何内容之前，请先存储幂等键。

Webhook 安全与幂等性

当 webhook 配置了 secret 时，GrowSurf 会对 webhook 投递进行签名：每次投递都包含一个使用该密钥计算的 GrowSurf-Signature HMAC 头（该密钥是只写的，永远不会返回）。为了安全地使用 webhook，我们建议：

• 在 webhook 上设置 secret，并在接收时验证 GrowSurf-Signature 头

• 验证负载结构和预期的事件类型

• 使用幂等键对 webhook 事件去重，因为同一事件可能到达多次

GrowSurf MCP 服务器提供了一个辅助工具（growsurf_webhook_normalize），用于规范化 webhook 负载并生成尽力而为的幂等键，以简化安全的 webhook 处理。

开发与测试

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 客户快速实施推荐项目和联盟项目。