gravity-ads-mcp

Local MCP server for the Gravity advertiser dashboard API. Create, edit, pause, and archive campaigns — and pull all your reporting — from any MCP-capable agent without your API key leaving your machine.

Gravity exposes a hosted MCP server at https://platform.trygravity.ai/mcp, but it is read-only. This package wraps the full Gravity Dashboard API (including create/edit) as a local stdio MCP server that runs via npx, so requests go directly from your computer to platform.trygravity.ai — nothing passes through a third party.

Prerequisites

• Node.js ≥ 18 (node --version to check)

• npx (bundled with npm; comes with Node)

• A Gravity advertiser API key — get yours at https://app.trygravity.ai under Settings → API Key

Related MCP server: Google Ads MCP Worker

Quickstart

Add the following to your MCP client's configuration file. Replace your-gravity-api-key with your actual key.

Claude Desktop

~/Library/Application Support/Claude/claude_desktop_config.json (macOS) or %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 users: If npx is not found, try "command": "cmd" with "args": ["/c", "npx", "-y", "gravity-ads-mcp"].

Claude Code

Create a .mcp.json file in your project root (or add to ~/.claude/mcp.json for global config):

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

Or add via 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 in your project root:

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

Note: opencode uses "environment" (not "env").

Windsurf

~/.codeium/windsurf/mcp_config.json:

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

Other Clients

Any MCP client that supports the mcpServers JSON format (same shape as Claude Desktop) can use this server. Add the following to your client's MCP config file:

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

Environment Variables

Tools

Account

Campaigns

Ad Groups & Ads

Reporting

Example Prompts

Once configured, try asking your agent:

• "List my active campaigns"

• "What's my ROAS for the last 14 days?"

• "Create a campaign called 'Summer Sale' with a $100/day budget, targeting US and CA, using a generative ad group for running shoes"

• "Pause all campaigns over $500 spend"

• "Show me ad group performance for campaign camp-456 over the last 7 days in America/New_York"

• "Create a manual ad group with these ads: headline '50% Off Running Shoes', copy 'Summer sale on all running shoes.', CTA 'Shop Now'"

• "What conversions did I get yesterday?"

• "Create a pixel for https://acme.com"

Security & Privacy

• Your GRAVITY_API_KEY is passed as a process environment variable and never logged or transmitted to any server other than platform.trygravity.ai.

• All API requests go directly from your machine to Gravity's API — no intermediary.

• Running via npx means no global install; the server starts fresh each session.

• Regenerate your key anytime at https://app.trygravity.ai under Settings → API Key.

Troubleshooting

Contributors

For local setup, building, testing, and publishing instructions, see DEVELOPMENT.md.

License

MIT