HYPD.AI

Permite que agentes de IA como Claude, Co-Pilot, Codex e outras ferramentas compatíveis criem, gerenciem e otimizem campanhas publicitárias no ChatGPT.

GitHub

Experimente este MCPPatrocinado

Documentação

openai-ads-mcp

Um servidor Model Context Protocol (MCP) para a API de OpenAI Ads (Anunciante). Ele permite que clientes compatíveis com MCP — Claude Desktop, Cursor, VS Code e outros — leiam suas campanhas, grupos de anúncios, anúncios e insights de desempenho do OpenAI Ads por meio de linguagem natural.

Somente leitura. Esta primeira versão apenas lê dados — ela nunca cria, edita ou pausa nada e nunca gasta orçamento. Ações de escrita estão no roadmap.

Não oficial. Este é um projeto da comunidade e não é afiliado ou endossado pela OpenAI. Veja o aviso legal.

Visão geral

A API de OpenAI Ads expõe a conta, campanhas, grupos de anúncios, anúncios e relatórios de um anunciante. Este servidor encapsula os endpoints de leitura dessa API como ferramentas MCP para que um assistente de IA possa responder perguntas como:

"Minha chave da API de OpenAI Ads está funcionando? A qual conta ela está vinculada?"
"Liste minhas campanhas ativas e seus orçamentos."
"Mostre gastos, cliques e CTR para a campanha cmp_123 nos últimos 30 dias, por dia."
"Quais anúncios no grupo de anúncios adg_456 ainda estão pendentes de revisão?"

Recursos

11 ferramentas somente leitura cobrindo conta, campanhas, grupos de anúncios, anúncios e insights em todos os níveis.
Respostas fiéis — o JSON da API é retornado como está, então nada se perde na tradução.
Erros claros — o status HTTP e o corpo do erro da API são exibidos ao modelo em vez de serem engolidos.
Ciente de micros — cada descrição de ferramenta explica a convenção de micros para que o assistente possa apresentar moeda legível para humanos.
Paginação por cursor pass-through (limit, order, after, before).
Zero instalação via npx — npx -y @hypd-ai/openai-ads-mcp, sem clone ou build.

Ferramentas

Ferramenta	O que faz
`get_ad_account`	Busca a conta de anúncios para a chave configurada. Ótimo como verificação de conectividade.
`list_campaigns`	Lista campanhas (objetivo, orçamento, segmentação por país).
`get_campaign`	Busca uma única campanha por ID.
`list_ad_groups`	Lista grupos de anúncios, opcionalmente filtrados por campanha.
`get_ad_group`	Busca um único grupo de anúncios por ID (configuração de lances, dicas de contexto).
`list_ads`	Lista anúncios, opcionalmente filtrados por grupo de anúncios.
`get_ad`	Busca um único anúncio por ID (criativo + status de revisão).
`get_account_insights`	Insights de desempenho para toda a conta.
`get_campaign_insights`	Insights de desempenho para uma campanha.
`get_ad_group_insights`	Insights de desempenho para um grupo de anúncios.
`get_ad_insights`	Insights de desempenho para um anúncio.

As ferramentas de insights aceitam since/until (YYYY-MM-DD) para a janela de relatório, além de time_granularity (daily/none), aggregation_level, fields, sort, filters, limit (1–10000) e cursores after/before.

Pré-requisitos

Node.js 20 ou mais recente.
Uma chave da API de OpenAI Ads. Crie uma conta de Ads em ads.openai.com (atualmente somente nos EUA), depois emita uma chave em Configurações → ads.openai.com/settings. Veja a documentação de início rápido e autenticação. Cada chave é limitada a uma única conta de anúncios.

Instalação e configuração

Os clientes MCP iniciam o servidor como um subprocesso e passam sua chave de API por meio de uma variável de ambiente.

Publicado no npm como @hypd-ai/openai-ads-mcp — npx o busca para você, então não há nada para clonar ou compilar. Para executar a versão mais recente não lançada main em vez disso, substitua @hypd-ai/openai-ads-mcp por github:HYPD-AI/openai-ads-mcp (seu primeiro lançamento compila a partir do código-fonte — veja Executando a partir do código-fonte).

Adicione o trecho para o seu cliente abaixo.

Claude Desktop

Edite seu 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"
      }
    }
  }
}

Reinicie o Claude Desktop e pergunte: "Use as ferramentas openai-ads para consultar minha conta de anúncios."

Cursor

Adicione a ~/.cursor/mcp.json (global) ou .cursor/mcp.json (por projeto):

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

VS Code

Adicione a .vscode/mcp.json. O VS Code pode solicitar a chave e armazená-la como um segredo 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}"
      }
    }
  }
}

Outros clientes MCP

Qualquer cliente que fale MCP sobre stdio funciona. Execute npx -y @hypd-ai/openai-ads-mcp (ou node /path/to/dist/index.js) com OPENAI_ADS_API_KEY definido no ambiente.

Configuração

Variável	Obrigatório	Padrão	Descrição
`OPENAI_ADS_API_KEY`	Sim	—	Sua chave da API de OpenAI Ads, enviada como token Bearer.
`OPENAI_ADS_BASE_URL`	Não	`https://api.ads.openai.com/v1`	Substitui a URL base da API (útil para testes ou um proxy).

Veja .env.example.

Uma nota sobre "micros"

Campos cujos nomes terminam em _micros — por exemplo, o lifetime_spend_limit_micros de uma campanha ou o max_bid_micros de um grupo de anúncios — são expressos em micros:

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

Portanto, um lifetime_spend_limit_micros de 25000000 é $25.00. Divida um valor _micros por 1.000.000 para exibir um valor legível, ou multiplique por 1.000.000 para converter no sentido contrário.

As métricas de insights não são micros. Valores de relatório como spend, cpc e cpm já estão na moeda da conta como decimais (por exemplo, spend: 42.75 significa $42.75).

Somente leitura por design

Esta versão registra apenas ferramentas de leitura (GET) — e cada uma é anotada com o readOnlyHint do MCP, para que clientes bem-comportados saibam que ela não pode alterar o estado. Não há nenhuma ferramenta aqui que possa criar, editar, pausar ou excluir qualquer coisa, e nada que possa gastar orçamento. Ações de escrita chegarão como uma etapa deliberada e revisada separadamente (veja Roadmap).

Executando a partir do código-fonte

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

Em seguida, aponte seu cliente MCP para o arquivo de entrada compilado:

{
  "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"
      }
    }
  }
}

Experimente com o MCP Inspector

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

Desenvolvimento

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/

Estrutura do projeto:

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)

Como as ferramentas mapeiam para a API

Todos os endpoints estão sob a URL base (padrão https://api.ads.openai.com/v1).

Ferramenta	Método	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

✍️ Ações de escrita — criar e atualizar (via POST) campanhas, grupos de anúncios e anúncios, além das transições de estado dedicadas (POST .../activate, .../pause, .../archive). O cliente HTTP já suporta POST; essas serão controladas por uma adesão explícita, pois alteram a entrega e os gastos.
🖼️ Uploads de criativos — POST /upload (JSON image_url ou multipart/form-data) para anexar imagens aos criativos de anúncios.
🌍 Segmentação de campanha — incluir/excluir país (targeting.locations.countries).
📈 Suporte à API de Conversões.
🌐 Transporte remoto/HTTP para implantações hospedadas.
📦 Lançamento publicado no npm para que npx -y openai-ads-mcp funcione imediatamente.

Contribuindo

Contribuições são bem-vindas! Por favor, leia CONTRIBUTING.md. Em resumo: abra uma issue para discutir mudanças substanciais, mantenha npm run lint && npm run typecheck && npm test verde e adicione testes para novos comportamentos.

Aviso legal

Este é um projeto não oficial, construído pela comunidade. Ele não é afiliado, endossado ou patrocinado pela OpenAI. "OpenAI" e nomes e logotipos relacionados são marcas registradas da OpenAI. Seu uso da API de OpenAI Ads por meio desta ferramenta está sujeito aos termos e políticas da OpenAI. A ferramenta é fornecida "como está", sem garantia de qualquer tipo — veja a licença.