OpenAI Ads MCP Server

Servidor MCP para a API de Anúncios da OpenAI e Anúncios do ChatGPT, com ferramentas tipadas para campanhas, criativos, públicos e insights.

GitHub

Experimente este MCPPatrocinado

Documentação

openai-ads-mcp

A Trakkr acompanha todo o funil de visibilidade em IA, orgânico e pago. Este é o complemento open-source do lado pago.

openai-ads-mcp é um servidor de Model Context Protocol tipado para OpenAI Ads, ChatGPT Ads e a API de Anunciantes da OpenAI. Ele permite que Claude, Cursor, Codex, VS Code e outros clientes MCP inspecionem contas de Ads, leiam insights de desempenho, criem campanhas pausadas, enviem criativos, gerenciem públicos e enviem eventos de conversão.

As pessoas costumam pesquisar por isso como ChatGPT Ads MCP porque os anúncios aparecem no ChatGPT. O pacote mantém o nome OpenAI Ads MCP porque os ChatGPT Ads são gerenciados por meio do OpenAI Ads, do Ads Manager e da API de Anunciantes da OpenAI.

Versão pública atual: 0.1.7.

Ele é distribuído em dois runtimes com os mesmos nomes de ferramentas, argumentos, padrões, modelo de segurança e referência OpenAPI embutida:

Runtime	Melhor instalação	Caminho do pacote
Python	`uvx openai-ads-mcp`	`python/`
Node	`npx -y openai-ads-mcp`	`typescript/`

O objetivo é simples: tornar o OpenAI Ads utilizável a partir de um assistente de IA sem facilitar gastos acidentais.

Instalação

Python com uvx:

export OPENAI_ADS_API_KEY="..."
export OPENAI_ADS_MCP_READONLY=1
uvx openai-ads-mcp

Python com pip:

python -m pip install openai-ads-mcp
export OPENAI_ADS_API_KEY="..."
export OPENAI_ADS_MCP_READONLY=1
openai-ads-mcp

Node com npx:

export OPENAI_ADS_API_KEY="..."
export OPENAI_ADS_MCP_READONLY=1
npx -y openai-ads-mcp

Node com npm:

npm install -g openai-ads-mcp
export OPENAI_ADS_API_KEY="..."
export OPENAI_ADS_MCP_READONLY=1
openai-ads-mcp

Para desenvolvimento local a partir deste monorepo:

cd services/openai-ads-mcp/python
python -m pip install -e .
python -m openai_ads_mcp

cd ../typescript
npm install
npm run build
node dist/index.js

Configuração

Crie uma chave de API de Ads no OpenAI Ads Manager e passe-a como variável de ambiente.

export OPENAI_ADS_API_KEY="..."

Primeira conexão recomendada:

export OPENAI_ADS_MCP_READONLY=1
uvx openai-ads-mcp

Ou com Node:

export OPENAI_ADS_MCP_READONLY=1
npx -y openai-ads-mcp

O modo somente leitura oculta todas as ferramentas de escrita. Elas estão ausentes do tools/list e não podem ser chamadas. Depois de confirmar a conta e inspecionar os dados, remova OPENAI_ADS_MCP_READONLY para habilitar gravações.

Variáveis de ambiente opcionais:

Variável	Finalidade
`OPENAI_ADS_API_KEY`	Chave bearer obrigatória para `https://api.ads.openai.com/v1`.
`OPENAI_ADS_API_BASE_URL`	Substituição HTTPS opcional para testes ou proxies.
`OPENAI_ADS_MCP_READONLY`	Defina como `1` ou `true` para registrar apenas ferramentas de leitura.
`OPENAI_ADS_BUDGET_CEILING_USD`	Proteção de orçamento opcional. Padrão `100`.

Metadados de descoberta

Este repositório inclui server.json para o Registro MCP oficial e diretórios MCP downstream. O nome canônico do registro é:

io.github.trakkr-aisearch/openai-ads-mcp

O pacote Node inclui o mcpName correspondente, e o README do pacote Python inclui o marcador mcp-name correspondente para verificação de propriedade no PyPI.

Os metadados do registro também anunciam o endpoint HTTP Streamable somente leitura hospedado:

https://openai-ads-mcp.trakkr.ai/mcp

Esse endpoint hospedado é para descoberta e uso somente leitura. Ele não armazena nem usa uma chave de API de OpenAI Ads de propriedade da Trakkr. O endpoint hospedado permite initialize anônimo e tools/list; chamadas de ferramentas da API de Ads exigem que o chamador envie X-OpenAI-Ads-API-Key.

Exemplos de clientes MCP

Claude Code, runtime Python

claude mcp add openai-ads \
  -e OPENAI_ADS_API_KEY=your_ads_key_here \
  -e OPENAI_ADS_MCP_READONLY=1 \
  -- uvx openai-ads-mcp

Claude Code, runtime Node

claude mcp add openai-ads \
  -e OPENAI_ADS_API_KEY=your_ads_key_here \
  -e OPENAI_ADS_MCP_READONLY=1 \
  -- npx -y openai-ads-mcp

Cursor ou Claude Desktop

{
  "mcpServers": {
    "openai-ads": {
      "command": "uvx",
      "args": ["openai-ads-mcp"],
      "env": {
        "OPENAI_ADS_API_KEY": "your_ads_key_here",
        "OPENAI_ADS_MCP_READONLY": "1"
      }
    }
  }
}

Use "command": "npx" e "args": ["-y", "openai-ads-mcp"] para o runtime Node.

Codex CLI

[mcp_servers.openai_ads]
command = "uvx"
args = ["openai-ads-mcp"]
env = { OPENAI_ADS_API_KEY = "your_ads_key_here", OPENAI_ADS_MCP_READONLY = "1" }

Registro MCP

Clientes compatíveis com o registro devem descobrir este servidor pelo nome:

io.github.trakkr-aisearch/openai-ads-mcp

Os metadados do registro listam npm, PyPI e o endpoint HTTP Streamable hospedado. O endpoint hospedado não exige chave de API para descoberta, mas exige X-OpenAI-Ads-API-Key para chamadas de ferramentas da API de Ads.

Docker

O repositório inclui Dockerfiles de produção para implantações HTTP Streamable hospedadas:

docker build -t openai-ads-mcp .
docker run --rm -p 8080:8080 \
  -e OPENAI_ADS_MCP_HOSTED_PUBLIC=1 \
  -e OPENAI_ADS_MCP_TELEMETRY_SALT="local-test-salt" \
  openai-ads-mcp

O typescript/Dockerfile mais restrito é usado pelo script de deploy do Cloud Run. Para uso local via stdio, prefira uvx openai-ads-mcp ou npx -y openai-ads-mcp.

HTTP Streamable

O runtime Node também pode servir MCP via HTTP Streamable para implantações hospedadas ou em equipe:

export OPENAI_ADS_MCP_HTTP_TOKEN="choose_a_long_random_token"
export OPENAI_ADS_MCP_READONLY=1
npx -y openai-ads-mcp --http

Padrões:

URL: http://127.0.0.1:8080/mcp localmente, ou https://your-host/mcp atrás de um proxy.
Verificações de saúde: GET /healthz, GET /health e GET /ready.
O modo remoto força OPENAI_ADS_MCP_READONLY=1 a menos que OPENAI_ADS_MCP_HTTP_ALLOW_WRITES=1 esteja definido.
OPENAI_ADS_MCP_HTTP_TOKEN protege o endpoint MCP com Authorization: Bearer <token>.
Os clientes podem enviar X-OpenAI-Ads-API-Key por requisição, ou o servidor pode usar um OPENAI_ADS_API_KEY no lado do servidor.

Variáveis de ambiente úteis para hospedagem:

Variável	Finalidade
`PORT` ou `OPENAI_ADS_MCP_HTTP_PORT`	Porta HTTP. Padrão `8080`.
`OPENAI_ADS_MCP_HTTP_PATH`	Caminho MCP. Padrão `/mcp`.
`OPENAI_ADS_MCP_HEALTH_PATH`	Caminho de saúde. Padrão `/healthz`.
`OPENAI_ADS_MCP_HTTP_TOKEN`	Token bearer opcional exigido por clientes hospedados.
`OPENAI_ADS_MCP_HTTP_ALLOW_WRITES`	Defina como `1` somente quando quiser expor ferramentas de escrita via HTTP.
`OPENAI_ADS_MCP_HTTP_CORS_ORIGIN`	Origem CORS opcional. Padrão `*`.

Para endpoints públicos hospedados, mantenha as gravações desabilitadas e exija que os usuários tragam sua própria chave de API de Ads por requisição. Não coloque uma chave de API de Ads compartilhada em configuração visível no navegador.

Modo público hospedado

Para um endpoint público de descoberta, use:

export OPENAI_ADS_MCP_HOSTED_PUBLIC=1
export OPENAI_ADS_MCP_TELEMETRY_SALT="long_random_value"
npx -y openai-ads-mcp --http

O modo público hospedado:

força o modo somente leitura
recusa iniciar se OPENAI_ADS_MCP_HTTP_ALLOW_WRITES=1
recusa iniciar se OPENAI_ADS_API_KEY estiver presente
rejeita X-OpenAI-Ads-API-Base-Url
permite initialize anônimo e tools/list
exige X-OpenAI-Ads-API-Key para chamadas de ferramentas da API de Ads
limita a taxa de descoberta e chamadas de ferramentas
registra apenas resumos editados, hashes, contagens, status, latência e metadados do cliente

O runbook de produção está em HOSTED_DEPLOY.md.

Superfície de ferramentas

Os runtimes Python e Node expõem as mesmas 27 ferramentas.

Grupo	Ferramentas
Conta	`get_account`
Campanhas	`list_campaigns`, `get_campaign`, `create_campaign`, `update_campaign`, `set_campaign_state`
Grupos de anúncios	`list_ad_groups`, `get_ad_group`, `create_ad_group`, `update_ad_group`, `set_ad_group_state`
Anúncios	`list_ads`, `get_ad`, `upload_creative`, `create_ad`, `update_ad`, `set_ad_state`
Insights	`get_insights`
Públicos	`list_audiences`, `get_audience`, `search_geo`, `manage_audience`
Conversões	`manage_conversions`, `send_conversions`
Auxiliares	`build_campaign`, `draft_context_hints`, `bulk_ab_test_hints`

Ferramentas de alto uso

Ferramenta	O que faz
`get_account`	Obtém a conta de anúncios e confirma que a chave de API funciona.
`get_insights`	Lê insights de conta, campanha, grupo de anúncios ou anúncio com campos, filtros, ordenação, segmentos e paginação por cursor.
`create_campaign`	Cria uma campanha pausada com orçamento vitalício protegido, incluindo campanhas otimizadas para conversão com uma configuração de evento.
`upload_creative`	Envia uma URL de imagem ou arquivo de imagem local e retorna `file_id`.
`create_ad`	Cria um anúncio pausado. `chat_card` exige `target_url` e `file_id`.
`build_campaign`	Cria uma campanha pausada, um grupo de anúncios pausado e anúncios pausados em um fluxo protegido.
`draft_context_hints`	Elabora de forma determinística `context_hints` no formato da API, sem chamada oculta de LLM.
`send_conversions`	Envia eventos de conversão para `https://bzr.openai.com/v1/events?pid=...` após validação local, com `validate_only` opcional. Suporta `obref` e eventos de ciclo de vida de apps móveis.

get_insights aceita o formato atual de intervalo de tempo com tag, por exemplo:

{"type":"unix_range","start":1764547200,"end":1765152000}

O formato aninhado mais antigo é normalizado para compatibilidade retroativa.

Para otimização de conversão, passe bidding_type="conversions" e exatamente um valor de conversion_event_setting_ids para create_campaign. A campanha não pode usar o modo de feed de produtos, e os grupos de anúncios filhos devem cobrar por clique. build_campaign oferece o mesmo caminho por meio do argumento auxiliar singular conversion_event_setting_id. O lance é uma entrada de CPA mesmo que a OpenAI cobre o grupo de anúncios filho por clique.

A Bulk API da OpenAI continua em prévia limitada e não é exposta como uma ferramenta MCP geral. Objetos de campanha com feed de produtos são suportados, mas a conexão do feed e o upload do catálogo ainda acontecem no Ads Manager ou pelo fluxo SFTP suportado pela OpenAI.

Modelo de segurança

Este servidor pode afetar gastos reais com anúncios, então os padrões são deliberadamente cautelosos.

As ferramentas de criação usam pausado por padrão. build_campaign cria todos os objetos pausados.
As ativações são ferramentas separadas: set_campaign_state, set_ad_group_state e set_ad_state.
Os caminhos de definição de orçamento aplicam OPENAI_ADS_BUDGET_CEILING_USD, padrão 100.
Para exceder o teto, passe confirm_budget=True.
OPENAI_ADS_MCP_READONLY=1 oculta completamente todas as ferramentas de escrita.
A ingestão de conversões valida no máximo 1000 eventos por chamada, carimbos de data/hora com no máximo 7 dias de idade e carimbos de data/hora com no máximo 10 minutos no futuro.
Use validate_only=true para validar um lote de conversões sem ingeri-lo.
O servidor nunca registra chaves de API nem dados de usuário de conversão.

Anotações MCP são definidas em todas as ferramentas. Ferramentas de leitura usam readOnlyHint. Ferramentas de escrita usam readOnlyHint=false. Ferramentas de ativação e alteração de orçamento são marcadas como destrutivas e de mundo aberto para que os hosts possam solicitar confirmação antes de executá-las.

Exemplo prático

Primeiro, conecte-se com segurança:

export OPENAI_ADS_API_KEY="..."
export OPENAI_ADS_MCP_READONLY=1
uvx openai-ads-mcp

Pergunte ao seu assistente:

Call get_account and list_campaigns. Confirm the Ads key works and show me what already exists.

Depois reinicie sem o modo somente leitura e crie uma campanha pausada:

Use draft_context_hints for "AI visibility monitoring software" aimed at growth teams with comparison intent.

Then call build_campaign with:
- name: "AI visibility category test"
- budget_usd: 50
- ad_group: name "Growth teams", billing_event "click", max_bid_usd 1.25, context_hints from the draft
- ads: two chat_card variants using my uploaded file_id

Do not activate anything.

Revise a campanha, o grupo de anúncios, os anúncios, o orçamento, a segmentação e o status de revisão retornados. Quando estiver pronto para publicar, ative cada camada explicitamente:

Call set_campaign_state with state="activate".
Call set_ad_group_state with state="activate".
Call set_ad_state for the approved ad with state="activate".

A metade orgânica

Os posicionamentos pagos respondem: onde você comprou atenção?

A Trakkr responde: onde sua marca aparece organicamente no ChatGPT, Perplexity, Gemini, Claude, Google AI Overviews, Reddit, citações, rankings, concorrentes, sentimento, prompts, relatórios e ações?

Acompanhe o lado orgânico em trakkr.ai. Use o gerador da Trakkr em trakkr.ai/create quando quiser transformar lacunas de pesquisa em IA em briefings de conteúdo.

Este MCP também expõe um recurso opcional:

openai-ads://trakkr-visibility

Ele retorna um briefing curto pronto para colar que conecta a compra de posicionamentos de anúncios no ChatGPT ao acompanhamento da visibilidade orgânica no ChatGPT. Ele nunca é injetado nos resultados das ferramentas.

Desenvolvimento

Python:

cd services/openai-ads-mcp/python
python -m pytest -q
python -c "import openai_ads_mcp; print('ok')"

Node:

cd services/openai-ads-mcp/typescript
npm install
npm run build
npm test
OPENAI_ADS_MCP_READONLY=1 node dist/index.js

Verificação de desvio do OpenAPI:

cd services/openai-ads-mcp/typescript
npm run check:openapi
npm run check:docs

O fluxo de trabalho agendado executa ambas as verificações semanalmente. A comparação do OpenAPI detecta desvios de esquema. A verificação do guia cobre o comportamento atual documentado fora do esquema baixável, incluindo intervalos de insights com tag, obref, eventos de apps móveis, otimização de conversão, prontidão do anunciante, imagens obrigatórias de chat-card e a Bulk API em prévia limitada.

Status da versão

0.1.7 é a versão beta pública atual para npm, PyPI, o endpoint hospedado e a entrada ativa no Registro MCP. As versões dos metadados do registro são imutáveis, portanto correções apenas no registro neste repositório devem ser publicadas com a próxima versão do pacote. O trabalho de release é sincronizado com o repositório público dedicado antes da publicação. Consulte RELEASING.md.