OpenAI Ads MCP Server

Servidor MCP de OpenAI Ads y ChatGPT Ads para la API de anunciantes de OpenAI, con herramientas tipadas para campañas, creativos, audiencias e insights.

GitHub

Prueba este MCPPatrocinado

Documentación

openai-ads-mcp

Trakkr rastrea el embudo completo de visibilidad de IA, orgánico y de pago. Este es el complemento de código abierto para el lado de pago.

openai-ads-mcp es un servidor de Model Context Protocol tipado para OpenAI Ads, ChatGPT Ads y la API de Anunciantes de OpenAI. Permite que Claude, Cursor, Codex, VS Code y otros clientes MCP inspeccionen cuentas de Ads, lean información de rendimiento, creen campañas en pausa, suban creativos, gestionen audiencias y envíen eventos de conversión.

La gente suele buscar esto como un ChatGPT Ads MCP porque los anuncios aparecen en ChatGPT. El paquete mantiene el nombre OpenAI Ads MCP porque los anuncios de ChatGPT se gestionan a través de OpenAI Ads, Ads Manager y la API de Anunciantes de OpenAI.

Versión pública actual: 0.1.7.

Se distribuye en dos entornos de ejecución con los mismos nombres de herramientas, argumentos, valores predeterminados, modelo de seguridad y referencia OpenAPI incluida:

Entorno	Mejor instalación	Ruta del paquete
Python	`uvx openai-ads-mcp`	`python/`
Node	`npx -y openai-ads-mcp`	`typescript/`

El objetivo es simple: hacer que OpenAI Ads sea utilizable desde un asistente de IA sin que sea fácil activar gastos por accidente.

Instalación

Python con uvx:

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

Python con pip:

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

Node con npx:

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

Node con npm:

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

Para desarrollo local desde este monorepositorio:

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

Configuración

Crea una clave de API de Ads en OpenAI Ads Manager y luego pásala como variable de entorno.

export OPENAI_ADS_API_KEY="..."

Primera conexión recomendada:

export OPENAI_ADS_MCP_READONLY=1
uvx openai-ads-mcp

O con Node:

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

El modo de solo lectura oculta todas las herramientas de escritura. Están ausentes de tools/list y no se pueden llamar. Una vez que hayas confirmado la cuenta e inspeccionado los datos, desactiva OPENAI_ADS_MCP_READONLY para habilitar las escrituras.

Variables de entorno opcionales:

Variable	Propósito
`OPENAI_ADS_API_KEY`	Clave bearer requerida para `https://api.ads.openai.com/v1`.
`OPENAI_ADS_API_BASE_URL`	Anulación HTTPS opcional para pruebas o proxies.
`OPENAI_ADS_MCP_READONLY`	Establecer en `1` o `true` para registrar solo herramientas de lectura.
`OPENAI_ADS_BUDGET_CEILING_USD`	Límite de presupuesto opcional. Predeterminado `100`.

Metadatos de descubrimiento

Este repositorio incluye server.json para el Registro MCP oficial y directorios MCP posteriores. El nombre canónico del registro es:

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

El paquete de Node incluye el mcpName correspondiente, y el README del paquete de Python incluye el marcador mcp-name correspondiente para la verificación de propiedad en PyPI.

Los metadatos del registro también anuncian el endpoint HTTP Streamable de solo lectura alojado:

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

Ese endpoint alojado es para descubrimiento y uso de solo lectura. No almacena ni utiliza una clave de API de OpenAI Ads propiedad de Trakkr. El endpoint alojado permite initialize anónimo y tools/list; las llamadas a herramientas de la API de Ads requieren que el llamador envíe X-OpenAI-Ads-API-Key.

Ejemplos de clientes MCP

Claude Code, entorno 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, entorno 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 o 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"
      }
    }
  }
}

Usa "command": "npx" y "args": ["-y", "openai-ads-mcp"] para el entorno 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

Los clientes compatibles con el registro deben descubrir este servidor por nombre:

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

Los metadatos del registro enumeran npm, PyPI y el endpoint HTTP Streamable alojado. El endpoint alojado no requiere una clave de API para el descubrimiento, pero sí requiere X-OpenAI-Ads-API-Key para las llamadas a herramientas de la API de Ads.

Docker

El repositorio incluye Dockerfiles de producción para implementaciones HTTP Streamable alojadas:

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

El typescript/Dockerfile más específico se usa en el script de implementación de Cloud Run. Para uso local con stdio, prefiere uvx openai-ads-mcp o npx -y openai-ads-mcp.

HTTP Streamable

El entorno Node también puede servir MCP sobre HTTP Streamable para implementaciones alojadas o de equipo:

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

Valores predeterminados:

URL: http://127.0.0.1:8080/mcp localmente, o https://your-host/mcp detrás de un proxy.
Comprobaciones de salud: GET /healthz, GET /health y GET /ready.
El modo remoto fuerza OPENAI_ADS_MCP_READONLY=1 a menos que se establezca OPENAI_ADS_MCP_HTTP_ALLOW_WRITES=1.
OPENAI_ADS_MCP_HTTP_TOKEN protege el endpoint MCP con Authorization: Bearer <token>.
Los clientes pueden enviar X-OpenAI-Ads-API-Key por solicitud, o el servidor puede usar un OPENAI_ADS_API_KEY del lado del servidor.

Variables de entorno útiles para alojamiento:

Variable	Propósito
`PORT` o `OPENAI_ADS_MCP_HTTP_PORT`	Puerto HTTP. Predeterminado `8080`.
`OPENAI_ADS_MCP_HTTP_PATH`	Ruta MCP. Predeterminado `/mcp`.
`OPENAI_ADS_MCP_HEALTH_PATH`	Ruta de salud. Predeterminado `/healthz`.
`OPENAI_ADS_MCP_HTTP_TOKEN`	Token bearer opcional requerido por los clientes alojados.
`OPENAI_ADS_MCP_HTTP_ALLOW_WRITES`	Establecer en `1` solo cuando quieras exponer herramientas de escritura a través de HTTP.
`OPENAI_ADS_MCP_HTTP_CORS_ORIGIN`	Origen CORS opcional. Predeterminado `*`.

Para endpoints públicos alojados, mantén las escrituras deshabilitadas y exige que los usuarios traigan su propia clave de API de Ads por solicitud. No pongas una clave de API de Ads compartida en configuración visible en el navegador.

Modo público alojado

Para un endpoint de descubrimiento público, usa:

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

El modo público alojado:

fuerza el modo de solo lectura
se niega a iniciar si OPENAI_ADS_MCP_HTTP_ALLOW_WRITES=1
se niega a iniciar si OPENAI_ADS_API_KEY está presente
rechaza X-OpenAI-Ads-API-Base-Url
permite initialize anónimo y tools/list
requiere X-OpenAI-Ads-API-Key para llamadas a herramientas de la API de Ads
limita la velocidad de descubrimiento y llamadas a herramientas
registra solo resúmenes redactados, hashes, conteos, estado, latencia y metadatos del cliente

El runbook de producción está en HOSTED_DEPLOY.md.

Superficie de herramientas

Los entornos Python y Node exponen las mismas 27 herramientas.

Grupo	Herramientas
Cuenta	`get_account`
Campañas	`list_campaigns`, `get_campaign`, `create_campaign`, `update_campaign`, `set_campaign_state`
Grupos de anuncios	`list_ad_groups`, `get_ad_group`, `create_ad_group`, `update_ad_group`, `set_ad_group_state`
Anuncios	`list_ads`, `get_ad`, `upload_creative`, `create_ad`, `update_ad`, `set_ad_state`
Información	`get_insights`
Audiencias	`list_audiences`, `get_audience`, `search_geo`, `manage_audience`
Conversiones	`manage_conversions`, `send_conversions`
Ayudantes	`build_campaign`, `draft_context_hints`, `bulk_ab_test_hints`

Herramientas de uso frecuente

Herramienta	Qué hace
`get_account`	Obtiene la cuenta de anuncios y confirma que la clave de API funciona.
`get_insights`	Lee información de cuenta, campaña, grupo de anuncios o anuncio con campos, filtros, orden, segmentos y paginación con cursor.
`create_campaign`	Crea una campaña en pausa con un presupuesto de por vida protegido, incluidas campañas optimizadas para conversiones con una configuración de evento.
`upload_creative`	Sube una URL de imagen o un archivo de imagen local y devuelve `file_id`.
`create_ad`	Crea un anuncio en pausa. `chat_card` requiere `target_url` y `file_id`.
`build_campaign`	Crea una campaña en pausa, un grupo de anuncios en pausa y anuncios en pausa en un flujo de trabajo protegido.
`draft_context_hints`	Redacta de forma determinista `context_hints` con forma de API sin llamada oculta a LLM.
`send_conversions`	Envía eventos de conversión a `https://bzr.openai.com/v1/events?pid=...` después de validación local, con `validate_only` opcional. Admite `obref` y eventos del ciclo de vida de aplicaciones móviles.

get_insights acepta la forma actual de rango de tiempo etiquetado, por ejemplo:

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

La forma anidada más antigua se normaliza para compatibilidad hacia atrás.

Para optimización de conversiones, pasa bidding_type="conversions" y exactamente un valor de conversion_event_setting_ids a create_campaign. La campaña no puede usar el modo de feed de productos, y los grupos de anuncios secundarios deben facturar por clic. build_campaign ofrece el mismo camino a través de su argumento auxiliar singular conversion_event_setting_id. La oferta es una entrada de CPA aunque OpenAI facture al grupo de anuncios secundario por clic.

La API Bulk de OpenAI sigue siendo una vista previa limitada y no se expone como una herramienta MCP general. Los objetos de campaña con feed de productos son compatibles, pero la conexión del feed y la carga del catálogo aún se realizan en Ads Manager o mediante el flujo SFTP compatible de OpenAI.

Modelo de seguridad

Este servidor puede afectar el gasto real en anuncios, por lo que los valores predeterminados son deliberadamente cautelosos.

Las herramientas de creación tienen como predeterminado pausado. build_campaign crea cada objeto en pausa.
Las activaciones son herramientas separadas: set_campaign_state, set_ad_group_state y set_ad_state.
Las rutas de configuración de presupuesto aplican OPENAI_ADS_BUDGET_CEILING_USD, predeterminado 100.
Para superar el límite, pasa confirm_budget=True.
OPENAI_ADS_MCP_READONLY=1 oculta por completo todas las herramientas de escritura.
La ingesta de conversiones valida como máximo 1000 eventos por llamada, marcas de tiempo no anteriores a 7 días y marcas de tiempo no más de 10 minutos en el futuro.
Usa validate_only=true para validar un lote de conversiones sin ingerirlo.
El servidor nunca registra claves de API ni datos de usuario de conversiones.

Las anotaciones MCP se establecen en cada herramienta. Las herramientas de lectura usan readOnlyHint. Las herramientas de escritura usan readOnlyHint=false. Las herramientas de activación y cambio de presupuesto están marcadas como destructivas y de mundo abierto para que los hosts puedan solicitar confirmación antes de ejecutarlas.

Ejemplo práctico

Primero, conéctate de forma segura:

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

Pregunta a tu asistente:

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

Luego reinicia sin modo de solo lectura y crea una campaña en pausa:

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.

Revisa la campaña, el grupo de anuncios, los anuncios, el presupuesto, la segmentación y el estado de revisión devueltos. Cuando estés listo para publicar, activa cada capa explícitamente:

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

La mitad orgánica

Las ubicaciones de pago responden: ¿dónde compraste atención?

Trakkr responde: ¿dónde aparece tu marca orgánicamente en ChatGPT, Perplexity, Gemini, Claude, Google AI Overviews, Reddit, citas, rankings, competidores, sentimiento, prompts, informes y acciones?

Rastrea el lado orgánico en trakkr.ai. Usa el generador de Trakkr en trakkr.ai/create cuando quieras convertir brechas de búsqueda de IA en briefs de contenido.

Este MCP también expone un recurso opcional:

openai-ads://trakkr-visibility

Devuelve un brief breve listo para pegar que conecta la compra de ubicaciones de anuncios en ChatGPT con el seguimiento de la visibilidad orgánica en ChatGPT. Nunca se inyecta en los resultados de las herramientas.

Desarrollo

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

Verificación de desviación de OpenAPI:

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

El flujo de trabajo programado ejecuta ambas verificaciones semanalmente. La comparación de OpenAPI detecta desviaciones de esquema. La verificación de la guía cubre el comportamiento actual documentado fuera del esquema descargable, incluidos rangos de información etiquetados, obref, eventos de aplicaciones móviles, optimización de conversiones, preparación del anunciante, imágenes obligatorias de tarjetas de chat y la API Bulk de vista previa limitada.

Estado de la versión

0.1.7 es la versión beta pública actual para npm, PyPI, el endpoint alojado y la entrada del Registro MCP en vivo. Las versiones de los metadatos del registro son inmutables, por lo que las correcciones solo del registro en este repositorio deben enviarse con la próxima versión del paquete. El trabajo de lanzamiento se sincroniza con el repositorio público dedicado antes de publicar. Consulta RELEASING.md.