Openai Ads MCP

What openai-ads-mcp MCP server does

The openai-ads-mcp MCP server provides an MCP interface to the read endpoints of the OpenAI Ads Advertiser API. It lets compatible AI clients retrieve an ad account, inspect campaign and ad hierarchy, and request reporting data without building direct API calls into the client.

The server is read-only. Its tools do not create campaigns, modify targeting or bids, change ads, pause delivery, delete resources, or spend budget. Each tool is annotated as read-only for clients that use MCP tool hints.

Responses preserve the API's JSON structure. HTTP status codes and API error bodies are passed through to the model instead of being hidden, which can help identify invalid IDs, authentication problems, or other API failures.

How it works

An MCP client launches the server as a local subprocess and supplies the API credential through OPENAI_ADS_API_KEY. The server sends authenticated requests to the OpenAI Ads API using that key. Each key is scoped to one ad account, so the account returned by get_ad_account also serves as a basic connectivity and credential check.

The openai-ads-mcp MCP server supports clients that speak MCP over stdio. The README provides configurations for Claude Desktop, Cursor, and VS Code, and notes that other stdio-compatible clients can run the same command. The default API endpoint is https://api.ads.openai.com/v1; OPENAI_ADS_BASE_URL can override it for testing or a proxy.

Insights requests accept reporting dates in YYYY-MM-DD format. They can use daily or non-granular results, selected fields, sorting, filters, aggregation settings, result limits, and after or before cursors.

Setup and configuration

Use Node.js 20 or newer and create an OpenAI Ads account and API key. The README states that OpenAI Ads is currently US-only. Configure the server with:

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

The package is published as @hypd-ai/openai-ads-mcp, so no repository clone or local build is needed for the released version. For source-based use, the project documents cloning the repository, running npm install, building with npm run build, and launching dist/index.js with Node.

Tools and capabilities

The openai-ads-mcp MCP server includes 11 tools:

• Retrieve the configured ad account.
• List campaigns and fetch an individual campaign.
• List ad groups, optionally filtered by campaign, and fetch one by ID.
• List ads, optionally filtered by ad group, and fetch one by ID.
• Retrieve account-, campaign-, ad-group-, or ad-level insights.

Campaign results can include objectives, budgets, and country targeting. Ad-group results can include bidding configuration and context hints. Individual ad results can include creative data and review status.

Values ending in _micros, such as spend limits and maximum bids, use one million micros per currency unit. Insights values such as spend, cpc, and cpm are reported as currency decimals rather than micros.