Skip to main content
Glama
HYPD AI - OpenAI Ads

HYPD AI - OpenAI Ads

by HYPD-AI

openai-ads-mcp

A Model Context Protocol (MCP) server for the OpenAI Ads (Advertiser) API. It lets MCP-compatible clients — Claude Desktop, Cursor, VS Code, and others — read your OpenAI Ads campaigns, ad groups, ads, and performance insights through natural language.

npm CI License: MIT Node MCP

Read-only. This first release only reads data — it never creates, edits, or pauses anything and never spends budget. Write actions are on the roadmap.

Unofficial. This is a community project and is not affiliated with or endorsed by OpenAI. See the disclaimer.


Overview

The OpenAI Ads API exposes an advertiser's account, campaigns, ad groups, ads, and reporting. This server wraps the read endpoints of that API as MCP tools so an AI assistant can answer questions like:

  • "Is my OpenAI Ads API key working? What account is it tied to?"

  • "List my active campaigns and their budgets."

  • "Show spend, clicks, and CTR for campaign cmp_123 over the last 30 days, by day."

  • "Which ads in ad group adg_456 are still pending review?"

Related MCP server: PaidSync MCP Server

Features

  • 11 read-only tools covering the account, campaigns, ad groups, ads, and insights at every level.

  • Faithful responses — the API's JSON is returned as-is, so nothing is lost in translation.

  • Clear errors — HTTP status and the API error body are surfaced to the model instead of being swallowed.

  • Micros-aware — every tool description explains the micros convention so the assistant can present human-readable currency.

  • Cursor pagination passthrough (limit, order, after, before).

  • Zero-install via npx — npx -y @hypd-ai/openai-ads-mcp, no clone or build.

Tools

Tool

What it does

get_ad_account

Fetch the ad account for the configured key. Great as a connectivity check.

list_campaigns

List campaigns (objective, budget, country targeting).

get_campaign

Fetch a single campaign by ID.

list_ad_groups

List ad groups, optionally filtered by campaign.

get_ad_group

Fetch a single ad group by ID (bidding config, context hints).

list_ads

List ads, optionally filtered by ad group.

get_ad

Fetch a single ad by ID (creative + review status).

get_account_insights

Performance insights for the whole account.

get_campaign_insights

Performance insights for one campaign.

get_ad_group_insights

Performance insights for one ad group.

get_ad_insights

Performance insights for one ad.

Insights tools accept since/until (YYYY-MM-DD) for the reporting window, plus time_granularity (daily/none), aggregation_level, fields, sort, filters, limit (1–10000), and after/before cursors.

Prerequisites

Installation & configuration

MCP clients launch the server as a subprocess and pass your API key via an environment variable.

Published on npm as @hypd-ai/openai-ads-mcp — npx fetches it for you, so there's nothing to clone or build. To run the latest unreleased main instead, replace @hypd-ai/openai-ads-mcp with github:HYPD-AI/openai-ads-mcp (its first launch builds from source — see Running from source).

Add the snippet for your client below.

Claude Desktop

Edit your claude_desktop_config.json:

  • macOS: ~/Library/Application Support/Claude/claude_desktop_config.json

  • Windows: %APPDATA%\Claude\claude_desktop_config.json

{
  "mcpServers": {
    "openai-ads": {
      "command": "npx",
      "args": ["-y", "@hypd-ai/openai-ads-mcp"],
      "env": {
        "OPENAI_ADS_API_KEY": "your-openai-ads-api-key"
      }
    }
  }
}

Restart Claude Desktop, then ask: "Use the openai-ads tools to look up my ad account."

Cursor

Add to ~/.cursor/mcp.json (global) or .cursor/mcp.json (per-project):

{
  "mcpServers": {
    "openai-ads": {
      "command": "npx",
      "args": ["-y", "@hypd-ai/openai-ads-mcp"],
      "env": {
        "OPENAI_ADS_API_KEY": "your-openai-ads-api-key"
      }
    }
  }
}

VS Code

Add to .vscode/mcp.json. VS Code can prompt for the key and store it as a secret via inputs:

{
  "inputs": [
    {
      "type": "promptString",
      "id": "openai_ads_api_key",
      "description": "OpenAI Ads API key",
      "password": true
    }
  ],
  "servers": {
    "openai-ads": {
      "command": "npx",
      "args": ["-y", "@hypd-ai/openai-ads-mcp"],
      "env": {
        "OPENAI_ADS_API_KEY": "${input:openai_ads_api_key}"
      }
    }
  }
}

Other MCP clients

Any client that speaks MCP over stdio works. Run npx -y @hypd-ai/openai-ads-mcp (or node /path/to/dist/index.js) with OPENAI_ADS_API_KEY set in the environment.

Configuration

Variable

Required

Default

Description

OPENAI_ADS_API_KEY

Yes

—

Your OpenAI Ads API key, sent as a Bearer token.

OPENAI_ADS_BASE_URL

No

https://api.ads.openai.com/v1

Override the API base URL (useful for testing or a proxy).

See .env.example.

A note on "micros"

Fields whose names end in _micros — for example a campaign's lifetime_spend_limit_micros or an ad group's max_bid_micros — are expressed in micros:

1,000,000 micros = 1 unit of the account's currency   (e.g. $1.00 = 1,000,000 micros)

So a lifetime_spend_limit_micros of 25000000 is $25.00. Divide a _micros value by 1,000,000 to display a human amount, or multiply by 1,000,000 to convert the other way.

Insights metrics are not micros. Reporting values like spend, cpc, and cpm are already in the account's currency as decimals (e.g. spend: 42.75 means $42.75).

Read-only by design

This release registers only read (GET) tools — and each one is annotated with the MCP readOnlyHint, so well-behaved clients know it cannot mutate state. There is no tool here that can create, edit, pause, or delete anything, and nothing that can spend budget. Write actions will arrive as a deliberate, separately reviewed step (see Roadmap).

Running from source

git clone https://github.com/hypd-ai/openai-ads-mcp.git
cd openai-ads-mcp
npm install
npm run build

Then point your MCP client at the built entry file:

{
  "mcpServers": {
    "openai-ads": {
      "command": "node",
      "args": ["/absolute/path/to/openai-ads-mcp/dist/index.js"],
      "env": {
        "OPENAI_ADS_API_KEY": "your-openai-ads-api-key"
      }
    }
  }
}

Try it with the MCP Inspector

OPENAI_ADS_API_KEY=your-key npx @modelcontextprotocol/inspector node dist/index.js

Development

npm install          # install dependencies
npm run dev          # rebuild on change (tsup --watch)
npm run typecheck    # tsc --noEmit
npm run lint         # eslint
npm run format       # prettier --write
npm test             # vitest
npm run build        # bundle to dist/

Project layout:

src/
  index.ts        # bin entry: load config, build server, connect stdio
  server.ts       # buildServer(): McpServer + register all tools
  client.ts       # OpenAIAdsClient: auth, URL building, errors
  config.ts       # environment parsing & validation
  schemas.ts      # shared zod shapes (pagination, insights) + micros note
  tools/          # one file per resource (account, campaigns, ad-groups, ads, insights)
test/             # vitest specs (config, client, in-memory server)

How tools map to the API

All endpoints are under the base URL (default https://api.ads.openai.com/v1).

Tool

Method

Endpoint

get_ad_account

GET

/ad_account

list_campaigns

GET

/campaigns

get_campaign

GET

/campaigns/{campaign_id}

list_ad_groups

GET

/ad_groups

get_ad_group

GET

/ad_groups/{ad_group_id}

list_ads

GET

/ads

get_ad

GET

/ads/{ad_id}

get_account_insights

GET

/ad_account/insights

get_campaign_insights

GET

/campaigns/{campaign_id}/insights

get_ad_group_insights

GET

/ad_groups/{ad_group_id}/insights

get_ad_insights

GET

/ads/{ad_id}/insights

Roadmap

  • ✍️ Write actions — create & update (via POST) campaigns, ad groups, and ads, plus the dedicated state transitions (POST .../activate, .../pause, .../archive). The HTTP client already supports POST; these will be gated behind an explicit opt-in, since they change delivery and spend.

  • 🖼️ Creative uploads — POST /upload (JSON image_url or multipart/form-data) to attach images to ad creatives.

  • 🌍 Campaign targeting — country include/exclude (targeting.locations.countries).

  • 📈 Conversions API support.

  • 🌐 Remote/HTTP transport for hosted deployments.

  • 📦 Published npm release so npx -y openai-ads-mcp works out of the box.

Contributing

Contributions are welcome! Please read CONTRIBUTING.md. In short: open an issue to discuss substantial changes, keep npm run lint && npm run typecheck && npm test green, and add tests for new behavior.

Disclaimer

This is an unofficial, community-built project. It is not affiliated with, endorsed by, or sponsored by OpenAI. "OpenAI" and related names and logos are trademarks of OpenAI. Your use of the OpenAI Ads API through this tool is subject to OpenAI's terms and policies. The tool is provided "as is", without warranty of any kind — see the license.

License

MIT © HYPD AI

Available Tools

11 tools
get_account_insightsGet ad account insightsA
Read-only

Retrieve performance insights aggregated across the entire ad account. Returns a list response (data[] with first_id/last_id/has_more for paging). Each row carries id, start_time, end_time, plus the projected fields such as impressions, clicks, spend, ctr, cpc, cpm, readable_time, campaign_name, ad_group_name, and ad_name. Combine aggregation_level, sort, and limit to rank entities (e.g. the top ad by clicks). Monetary metrics (spend, cpc, cpm) are in the account's currency as decimal values, not micros.

Inputs: since, until, time_granularity, aggregation_level, +6 more.

get_adGet adA
Read-only

Fetch a single ad by its ID, including its creative and review status.

Inputs: ad_id (required).

get_ad_accountGet ad accountA
Read-only

Fetch the ad account associated with the configured API key. Use this as a connectivity check to confirm the key is valid, and to read account-level details such as name, currency, status, and timezone. Each API key is scoped to a single ad account.

Inputs: no named parameters.

get_ad_groupGet ad groupA
Read-only

Fetch a single ad group by its ID, including its status, bidding configuration, and context hints. Monetary values are expressed in micros: 1,000,000 micros = 1 unit of the account's currency (for example, $1.00 = 1,000,000 micros). Divide any *_micros value by 1,000,000 to show a human-readable amount, and multiply by 1,000,000 to convert a currency amount into micros.

Inputs: ad_group_id (required).

get_ad_group_insightsGet ad group insightsA
Read-only

Retrieve performance insights for a single ad group. Returns a list response (data[] with first_id/last_id/has_more for paging). Each row carries id, start_time, end_time, plus the projected fields such as impressions, clicks, spend, ctr, cpc, cpm, readable_time, campaign_name, ad_group_name, and ad_name. Combine aggregation_level, sort, and limit to rank entities (e.g. the top ad by clicks). Monetary metrics (spend, cpc, cpm) are in the account's currency as decimal values, not micros.

Inputs: ad_group_id (required), since, until, time_granularity, +7 more.

get_ad_insightsGet ad insightsA
Read-only

Retrieve performance insights for a single ad. Returns a list response (data[] with first_id/last_id/has_more for paging). Each row carries id, start_time, end_time, plus the projected fields such as impressions, clicks, spend, ctr, cpc, cpm, readable_time, campaign_name, ad_group_name, and ad_name. Combine aggregation_level, sort, and limit to rank entities (e.g. the top ad by clicks). Monetary metrics (spend, cpc, cpm) are in the account's currency as decimal values, not micros.

Inputs: ad_id (required), since, until, time_granularity, +7 more.

get_campaignGet campaignA
Read-only

Fetch a single campaign by its ID, including its objective, status, budget, and targeting. Monetary values are expressed in micros: 1,000,000 micros = 1 unit of the account's currency (for example, $1.00 = 1,000,000 micros). Divide any *_micros value by 1,000,000 to show a human-readable amount, and multiply by 1,000,000 to convert a currency amount into micros.

Inputs: campaign_id (required).

get_campaign_insightsGet campaign insightsA
Read-only

Retrieve performance insights for a single campaign. Returns a list response (data[] with first_id/last_id/has_more for paging). Each row carries id, start_time, end_time, plus the projected fields such as impressions, clicks, spend, ctr, cpc, cpm, readable_time, campaign_name, ad_group_name, and ad_name. Combine aggregation_level, sort, and limit to rank entities (e.g. the top ad by clicks). Monetary metrics (spend, cpc, cpm) are in the account's currency as decimal values, not micros.

Inputs: campaign_id (required), since, until, time_granularity, +7 more.

list_ad_groupsList ad groupsA
Read-only

List ad groups within a campaign (campaign_id is required). Ad groups belong to a campaign and hold the bidding configuration and context hints. Supports cursor pagination (order, after/before; the response includes first_id, last_id, and has_more). Monetary values are expressed in micros: 1,000,000 micros = 1 unit of the account's currency (for example, $1.00 = 1,000,000 micros). Divide any *_micros value by 1,000,000 to show a human-readable amount, and multiply by 1,000,000 to convert a currency amount into micros.

Inputs: campaign_id (required), limit, order, after, +1 more.

list_adsList adsA
Read-only

List ads within an ad group (ad_group_id is required). Each ad holds a creative (title, body, target URL, image) and a review_status (in_review, approved, or rejected). Supports cursor pagination (order, after/before; the response includes first_id, last_id, and has_more).

Inputs: ad_group_id (required), limit, order, after, +1 more.

list_campaignsList campaignsA
Read-only

List campaigns in the ad account. Campaigns are the top-level objects that define the objective, budget, and country targeting. Supports cursor pagination; the response includes first_id, last_id, and has_more. Monetary values are expressed in micros: 1,000,000 micros = 1 unit of the account's currency (for example, $1.00 = 1,000,000 micros). Divide any *_micros value by 1,000,000 to show a human-readable amount, and multiply by 1,000,000 to convert a currency amount into micros.

Inputs: limit, order, after, before.

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    TDQS

    A4.2/5.0

    Scored across 11 tools

    Disambiguation5/5

    Each tool targets a distinct entity or scope (account, campaign, ad group, ad) with clear separation between get, list, and insights operations. No overlaps or ambiguity between tool purposes.

    Naming Consistency5/5

    All tool names follow a consistent verb_noun pattern: get_<singular_entity> or list_<plural_entity> and get_<entity>_insights. The naming is predictable and uniform across the entire set.

    Tool Count5/5

    With 11 tools covering account, campaign, ad group, and ad entities plus their insights, the count is well-scoped for an ad platform's read surface. No redundant or missing core tools.

    Completeness2/5

    The tool set is entirely read-only, lacking any create, update, or delete operations. This is a critical gap for an ad management platform, as agents cannot perform any mutations. Significant missing functionality for typical ad workflows.

    Maintenance

    ActivityInactive
    ResponsivenessNo recent community issues

    Related MCP Connectors

    Related MCP Servers

    • A
      license
      Not graded
      quality
      B
      maintenance
      Enables AI assistants to create, analyze, and optimize ad campaigns across Google Ads, Meta Ads, TikTok Ads, LinkedIn Ads, Amazon Ads, and ChatGPT Ads through natural language using 400+ tools.
      108
      MIT
    • A
      license
      Not graded
      quality
      F
      maintenance
      Connects Google Ads, Meta Ads, and LinkedIn Ads to AI assistants, enabling natural language ad campaign management, reporting, and optimization across platforms.
      MIT
    • A
      license
      B
      quality
      C
      maintenance
      Enables managing ChatGPT Advertiser campaigns from MCP-capable agents, including campaign creation, creative uploads, audience management, conversions setup, and insights retrieval.
      89
      31 npm
      MIT
    • A
      license
      Not graded
      quality
      C
      maintenance
      Enables AI assistants to create, manage, and optimize advertising campaigns across 14 ad and measurement platforms through a single MCP endpoint, with over 530 executable tools.
      4
      MIT