gravity-ads-mcp

适用于 Gravity 广告主仪表盘 API 的本地 MCP 服务器。你可以从任何支持 MCP 的代理中创建、编辑、暂停和归档广告系列，并拉取所有报告数据，而无需将 API 密钥带离你的机器。

Gravity 在 https://platform.trygravity.ai/mcp 提供了一个托管的 MCP 服务器，但它是只读的。本包将完整的 Gravity Dashboard API（包括创建/编辑）封装为一个通过 npx 运行的本地 stdio MCP 服务器，因此请求会直接从你的计算机发送到 platform.trygravity.ai——不会经过任何第三方。

前提条件

• Node.js ≥ 18（运行 node --version 检查）

• npx（随 npm 捆绑；Node 自带）

• Gravity 广告主 API 密钥——在 https://app.trygravity.ai 的 设置 → API 密钥 下获取

Related MCP server: Nitrosend

快速开始

将以下内容添加到你的 MCP 客户端配置文件中。将 your-gravity-api-key 替换为你的实际密钥。

Claude Desktop

~/Library/Application Support/Claude/claude_desktop_config.json（macOS）或 %APPDATA%\Claude\claude_desktop_config.json（Windows）：

{
  "mcpServers": {
    "gravity": {
      "command": "npx",
      "args": ["-y", "gravity-ads-mcp"],
      "env": {
        "GRAVITY_API_KEY": "your-gravity-api-key"
      }
    }
  }
}

Windows 用户： 如果找不到 npx，请尝试使用 "command": "cmd" 并设置 "args": ["/c", "npx", "-y", "gravity-ads-mcp"]。

Claude Code

在你的项目根目录创建 .mcp.json 文件（或添加到 ~/.claude/mcp.json 以进行全局配置）：

{
  "mcpServers": {
    "gravity": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "gravity-ads-mcp"],
      "env": {
        "GRAVITY_API_KEY": "your-gravity-api-key"
      }
    }
  }
}

或者通过 CLI 添加：

claude mcp add gravity --env GRAVITY_API_KEY=your-gravity-api-key -- npx -y gravity-ads-mcp

Cursor

~/.cursor/mcp.json：

{
  "mcpServers": {
    "gravity": {
      "command": "npx",
      "args": ["-y", "gravity-ads-mcp"],
      "env": {
        "GRAVITY_API_KEY": "your-gravity-api-key"
      }
    }
  }
}

opencode

在你的项目根目录中的 opencode.json：

{
  "$schema": "https://opencode.ai/config.json",
  "mcp": {
    "gravity": {
      "type": "local",
      "command": ["npx", "-y", "gravity-ads-mcp"],
      "environment": {
        "GRAVITY_API_KEY": "your-gravity-api-key"
      }
    }
  }
}

注意：opencode 使用 "environment"（而不是 "env"）。

Windsurf

~/.codeium/windsurf/mcp_config.json：

{
  "mcpServers": {
    "gravity": {
      "command": "npx",
      "args": ["-y", "gravity-ads-mcp"],
      "env": {
        "GRAVITY_API_KEY": "your-gravity-api-key"
      }
    }
  }
}

其他客户端

任何支持 mcpServers JSON 格式（与 Claude Desktop 相同结构）的 MCP 客户端都可以使用此服务器。将以下内容添加到你的客户端的 MCP 配置文件中：

{
  "mcpServers": {
    "gravity": {
      "command": "npx",
      "args": ["-y", "gravity-ads-mcp"],
      "env": {
        "GRAVITY_API_KEY": "your-gravity-api-key"
      }
    }
  }
}

环境变量

工具

账户

广告系列

广告组与广告

报告

示例提示

配置完成后，你可以尝试向代理提问：

• 列出我活跃的广告系列

• 我最近 14 天的 ROAS 是多少？

• 创建一个名为“夏季促销”的广告系列，每日预算 100 美元，定向美国和加拿大，使用针对跑鞋的生成式广告组

• 暂停所有花费超过 500 美元的广告系列

• 以 America/New_York 时区显示广告系列 camp-456 过去 7 天的广告组表现

• 创建一个手动广告组，包含以下广告：标题“跑鞋五折”，文案“所有跑鞋夏季促销。”，CTA“立即购买”

• 我昨天获得了哪些转化？

• 为 https://acme.com 创建一个像素

安全与隐私

• 你的 GRAVITY_API_KEY 作为进程环境变量传递，绝不会被记录或传输到除 platform.trygravity.ai 以外的任何服务器。

• 所有 API 请求都直接从你的机器发送到 Gravity 的 API——没有中间方。

• 通过 npx 运行意味着无需全局安装；服务器会在每次会话中全新启动。

• 随时在 https://app.trygravity.ai 的 设置 → API 密钥 下重新生成你的密钥。

故障排除

贡献者

有关本地设置、构建、测试和发布的说明，请参阅 DEVELOPMENT.md。

许可证

MIT