HYPD.AI

Permite que agentes de IA como Claude, Co-Pilot, Codex y otras herramientas compatibles creen, gestionen y optimicen campañas publicitarias en ChatGPT.

GitHub

Prueba este MCPPatrocinado

Documentación

openai-ads-mcp

Un servidor Protocolo de Contexto de Modelo (MCP) para la API de OpenAI Ads (Anunciante). Permite que clientes compatibles con MCP — Claude Desktop, Cursor, VS Code y otros — lean tus campañas, grupos de anuncios, anuncios y perspectivas de rendimiento de OpenAI Ads mediante lenguaje natural.

Solo lectura. Esta primera versión solo lee datos — nunca crea, edita ni pausa nada, y nunca gasta presupuesto. Las acciones de escritura están en la hoja de ruta.

No oficial. Este es un proyecto comunitario y no está afiliado ni respaldado por OpenAI. Consulta el aviso legal.

Descripción general

La API de OpenAI Ads expone la cuenta, campañas, grupos de anuncios, anuncios e informes de un anunciante. Este servidor envuelve los endpoints de lectura de esa API como herramientas MCP para que un asistente de IA pueda responder preguntas como:

"¿Está funcionando mi clave de API de OpenAI Ads? ¿A qué cuenta está vinculada?"
"Enumera mis campañas activas y sus presupuestos."
"Muestra gasto, clics y CTR para la campaña cmp_123 en los últimos 30 días, por día."
"¿Qué anuncios en el grupo de anuncios adg_456 siguen pendientes de revisión?"

Características

11 herramientas de solo lectura que cubren la cuenta, campañas, grupos de anuncios, anuncios y perspectivas en todos los niveles.
Respuestas fieles — el JSON de la API se devuelve tal cual, por lo que nada se pierde en la traducción.
Errores claros — el estado HTTP y el cuerpo del error de la API se muestran al modelo en lugar de ser ignorados.
Consciente de micros — cada descripción de herramienta explica la convención de micros para que el asistente pueda presentar moneda legible para humanos.
Paginación por cursor de paso (limit, order, after, before).
Cero instalación mediante npx — npx -y @hypd-ai/openai-ads-mcp, sin clonar ni compilar.

Herramientas

Herramienta	Qué hace
`get_ad_account`	Obtiene la cuenta de anuncios para la clave configurada. Ideal como comprobación de conectividad.
`list_campaigns`	Enumera campañas (objetivo, presupuesto, segmentación por país).
`get_campaign`	Obtiene una sola campaña por ID.
`list_ad_groups`	Enumera grupos de anuncios, opcionalmente filtrados por campaña.
`get_ad_group`	Obtiene un solo grupo de anuncios por ID (configuración de oferta, sugerencias de contexto).
`list_ads`	Enumera anuncios, opcionalmente filtrados por grupo de anuncios.
`get_ad`	Obtiene un solo anuncio por ID (creativo + estado de revisión).
`get_account_insights`	Perspectivas de rendimiento para toda la cuenta.
`get_campaign_insights`	Perspectivas de rendimiento para una campaña.
`get_ad_group_insights`	Perspectivas de rendimiento para un grupo de anuncios.
`get_ad_insights`	Perspectivas de rendimiento para un anuncio.

Las herramientas de perspectivas aceptan since/until (YYYY-MM-DD) para la ventana de informes, además de time_granularity (daily/none), aggregation_level, fields, sort, filters, limit (1–10000) y cursores after/before.

Requisitos previos

Node.js 20 o más reciente.
Una clave de API de OpenAI Ads. Crea una cuenta de Ads en ads.openai.com (actualmente solo EE. UU.), luego emite una clave desde Configuración → ads.openai.com/settings. Consulta la documentación de inicio rápido y autenticación. Cada clave está limitada a una sola cuenta de anuncios.

Instalación y configuración

Los clientes MCP inician el servidor como un subproceso y pasan tu clave de API mediante una variable de entorno.

Publicado en npm como @hypd-ai/openai-ads-mcp — npx lo obtiene por ti, por lo que no hay nada que clonar o compilar. Para ejecutar la última versión no publicada main en su lugar, reemplaza @hypd-ai/openai-ads-mcp con github:HYPD-AI/openai-ads-mcp (su primer lanzamiento compila desde el código fuente — consulta Ejecutar desde el código fuente).

Añade el fragmento para tu cliente a continuación.

Claude Desktop

Edita tu 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"
      }
    }
  }
}

Reinicia Claude Desktop y luego pregunta: "Usa las herramientas de openai-ads para consultar mi cuenta de anuncios."

Cursor

Añade a ~/.cursor/mcp.json (global) o .cursor/mcp.json (por proyecto):

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

VS Code

Añade a .vscode/mcp.json. VS Code puede solicitar la clave y almacenarla como secreto mediante 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}"
      }
    }
  }
}

Otros clientes MCP

Cualquier cliente que hable MCP sobre stdio funciona. Ejecuta npx -y @hypd-ai/openai-ads-mcp (o node /path/to/dist/index.js) con OPENAI_ADS_API_KEY configurado en el entorno.

Configuración

Variable	Obligatorio	Predeterminado	Descripción
`OPENAI_ADS_API_KEY`	Sí	—	Tu clave de API de OpenAI Ads, enviada como token Bearer.
`OPENAI_ADS_BASE_URL`	No	`https://api.ads.openai.com/v1`	Sobrescribe la URL base de la API (útil para pruebas o un proxy).

Consulta .env.example.

Una nota sobre "micros"

Los campos cuyos nombres terminan en _micros — por ejemplo, el lifetime_spend_limit_micros de una campaña o el max_bid_micros de un grupo de anuncios — se expresan en micros:

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

Así que un lifetime_spend_limit_micros de 25000000 es $25.00. Divide un valor _micros entre 1,000,000 para mostrar una cantidad legible, o multiplica por 1,000,000 para convertir en el otro sentido.

Las métricas de perspectivas no son micros. Los valores de informes como spend, cpc y cpm ya están en la moneda de la cuenta como decimales (por ejemplo, spend: 42.75 significa $42.75).

Solo lectura por diseño

Esta versión registra solo herramientas de lectura (GET) — y cada una está anotada con el readOnlyHint de MCP, para que los clientes bien comportados sepan que no puede mutar el estado. No hay ninguna herramienta aquí que pueda crear, editar, pausar o eliminar nada, y nada que pueda gastar presupuesto. Las acciones de escritura llegarán como un paso deliberado y revisado por separado (consulta Hoja de ruta).

Ejecutar desde el código fuente

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

Luego apunta tu cliente MCP al archivo 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"
      }
    }
  }
}

Pruébalo con el MCP Inspector

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

Desarrollo

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/

Estructura del proyecto:

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)

Cómo se asignan las herramientas a la API

Todos los endpoints están bajo la URL base (predeterminada https://api.ads.openai.com/v1).

Herramienta	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`

Hoja de ruta

✍️ Acciones de escritura — crear y actualizar (mediante POST) campañas, grupos de anuncios y anuncios, además de las transiciones de estado dedicadas (POST .../activate, .../pause, .../archive). El cliente HTTP ya admite POST; estas estarán detrás de una opción explícita, ya que cambian la entrega y el gasto.
🖼️ Cargas creativas — POST /upload (JSON image_url o multipart/form-data) para adjuntar imágenes a los creativos de anuncios.
🌍 Segmentación de campañas — incluir/excluir país (targeting.locations.countries).
📈 Soporte de API de conversiones.
🌐 Transporte remoto/HTTP para implementaciones alojadas.
📦 Publicación en npm para que npx -y openai-ads-mcp funcione de inmediato.

Contribuciones

¡Las contribuciones son bienvenidas! Por favor, lee CONTRIBUTING.md. En resumen: abre un issue para discutir cambios sustanciales, mantén npm run lint && npm run typecheck && npm test en verde y añade pruebas para el nuevo comportamiento.

Aviso legal

Este es un proyecto no oficial construido por la comunidad. No está afiliado, respaldado ni patrocinado por OpenAI. "OpenAI" y los nombres y logotipos relacionados son marcas comerciales de OpenAI. Tu uso de la API de OpenAI Ads a través de esta herramienta está sujeto a los términos y políticas de OpenAI. La herramienta se proporciona "tal cual", sin garantía de ningún tipo — consulta la licencia.