# openai-ads-mcp [Health: Active]

**Category:** 🎯 Marketing  
**Repository:** https://github.com/HYPD-AI/openai-ads-mcp  
**GitHub Stars:** 6  
**npm Downloads (last month):** 314  
**Views:** 5  
**Installs:** 0  
**Upvotes:** 0  
**Directory Page:** https://allmcps.com/mcp/openai-ads-mcp

## Description
Read-only MCP server for the OpenAI Ads API: campaigns, ad groups, ads, and insights.

## Tools
Capabilities this server exposes over MCP:

- **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.

## Claude Desktop Quick Installation
Install path detected from listing signals. Uses `npx` (confidence: high):

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

**Requires environment variables:** `OPENAI_ADS_API_KEY` — the values above are empty placeholders; fill in real credentials before running (see the repository for what each one is for).

## Documentation

## 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. Configure the server with:

```json
{
  "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.

_Full upstream README: https://allmcps.com/mcp/openai-ads-mcp/readme_