gravity-ads-mcp

Gravity 광고주 대시보드 API용 로컬 MCP 서버입니다. 캠페인 생성, 편집, 일시중지, 보관 — 그리고 모든 보고 데이터 조회를 MCP를 지원하는 모든 에이전트에서 수행할 수 있으며, API 키가 사용자의 컴퓨터를 벗어나지 않습니다.

Gravity는 https://platform.trygravity.ai/mcp에서 호스팅 MCP 서버를 제공하지만 읽기 전용입니다. 이 패키지는 전체 Gravity 대시보드 API(생성/편집 포함)를 npx로 실행되는 로컬 stdio MCP 서버로 감싸서, 요청이 사용자의 컴퓨터에서 platform.trygravity.ai로 직접 전달됩니다 — 제3자를 거치지 않습니다.

사전 요구사항

• Node.js ≥ 18 (node --version으로 확인)

• npx (npm에 포함되어 있으며 Node와 함께 설치됨)

• Gravity 광고주 API 키 — https://app.trygravity.ai의 설정 → API 키에서 발급받으세요

Related MCP server: Google Ads MCP Worker

빠른 시작

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는 얼마야?"

• "'Summer Sale'이라는 캠페인을 일일 예산 $100, US와 CA 타겟팅, 러닝화용 생성형 광고 그룹으로 만들어줘"

• "지출이 $500를 초과하는 모든 캠페인을 일시중지해줘"

• "camp-456 캠페인의 지난 7일간 광고 그룹 성과를 America/New_York 시간대로 보여줘"

• "다음 광고로 수동 광고 그룹을 만들어줘: 헤드라인 '50% Off Running Shoes', 카피 'Summer sale on all running shoes.', CTA 'Shop Now'"

• "어제 전환은 몇 건이었어?"

• "https://acme.com용 픽셀을 만들어줘"

보안 및 개인정보

• GRAVITY_API_KEY는 프로세스 환경 변수로 전달되며 절대 로그에 기록되거나 platform.trygravity.ai 이외의 서버로 전송되지 않습니다.

• 모든 API 요청은 사용자의 컴퓨터에서 Gravity API로 직접 전달됩니다 — 중개자가 없습니다.

• npx로 실행하므로 전역 설치가 필요 없으며, 서버는 세션마다 새로 시작됩니다.

• 키는 언제든지 https://app.trygravity.ai의 설정 → API 키에서 재생성할 수 있습니다.

문제 해결

기여자

로컬 설정, 빌드, 테스트 및 배포 지침은 DEVELOPMENT.md를 참조하세요.

라이선스

MIT