yandex-direct-mcp

Servidor MCP para Yandex Direct API v5. Conecta una cuenta publicitaria a un agente de IA (Claude Code, Cursor y cualquier otro cliente MCP): la tarea se plantea en texto normal, el agente reúne las llamadas API necesarias y analiza la respuesta.

Ты:    посмотри, куда за август ушёл бюджет и что откручивается без конверсий
Агент: [direct_report] → 12 кампаний, 340 фраз
       Расход 214 800 ₽. Кампания «Поиск / Бренд» — 38%, CPA 610 ₽.
       17 фраз потратили 31 400 ₽ при нуле конверсий — вот они, отключаем?

Sin dependencias: un solo archivo en Node.js, transporte stdio, solicitudes mediante fetch integrado.

• El token se almacena localmente en un archivo con permisos 600 y no sale a ningún sitio excepto api.direct.yandex.com.

• Los cambios requieren confirmación. El cliente MCP pide permiso para cada llamada; además hay un modo de «solo lectura» que bloquea los métodos de modificación a nivel de servidor.

• API completo, no un subconjunto. La herramienta universal direct_call cubre todos los servicios v5, desde campaigns hasta keywordsresearch.

Qué se puede hacer

Analítica. Informes por cualquier segmento y período: campañas, grupos, anuncios, frases clave, consultas de búsqueda, geo, dispositivos, hora del día, sexo y edad. Gasto, clics, CTR, CPC, conversiones, CPA, comparación de períodos. Análisis de consultas de búsqueda para detectar basura, búsqueda de frases con gasto sin conversiones.

Gestión. Creación y edición de campañas, grupos, anuncios, frases clave. Pujas y presupuestos diarios, incluso en lote, según una regla («CPA superior a 2000 ₽ → reducir la puja en un 20%»). Palabras negativas, activación y pausa, envío a moderación, ajustes de puja por geo, dispositivos y audiencias, retargeting.

Semántica. Comprobación de frecuencia de frases (keywordsresearch), directorios de regiones y zonas horarias (dictionaries).

Tareas periódicas. Resumen matutino del gasto de ayer, análisis semanal de consultas de búsqueda, alerta de sobrecosto, si el cliente MCP admite programación.

Escenarios detallados con ejemplos de solicitudes: docs/usage.md.

Related MCP server: Yandex Direct MCP Server

Requisitos

• Node.js 18 o superior (se necesita fetch integrado).

• Cuenta de Yandex Direct.

• Aplicación registrada en oauth.yandex.ru con solicitud aprobada para acceso a la API. Esta es la principal barrera y tarda de una hora a tres días; empieza por ahí: docs/registration.md.

Instalación

git clone https://github.com/iarbor04/yandex-direct-mcp.git
cd yandex-direct-mcp

No hay dependencias, no se necesita npm install.

Claude Code:

claude mcp add yandex-direct --scope user -- node "$PWD/server.js"

Cursor, Windsurf y otros clientes con configuración JSON:

{
  "mcpServers": {
    "yandex-direct": {
      "command": "node",
      "args": ["/абсолютный/путь/yandex-direct-mcp/server.js"]
    }
  }
}

Las herramientas aparecen al iniciar el cliente: después de añadir el servidor, reinicia la sesión.

Autorización

El orden es importante. Si no se hace en este orden, obtendrás el error 58 y perderás tiempo; nosotros lo perdimos.

1. Solicitud de acceso a la API

Registras la aplicación en oauth.yandex.ru y presentas la solicitud en la interfaz de Direct: «Mis solicitudes». La revisión se realiza en días laborables de la Federación Rusa de 10:00 a 19:00, de una hora a tres días, en períodos pico hasta siete días.

Qué escribir en el formulario (textos listos para todos los campos, incluida la descripción del esquema de interacción y el diagrama) — docs/registration.md.

Sin una solicitud aprobada, ni siquiera el sandbox funciona. Comprobado: api-sandbox.direct.yandex.com devuelve el mismo error 58 que la API de producción. No se puede depurar «con datos de prueba».

2. Token

./save-token.sh <CLIENT_ID>

El script mostrará el enlace de autorización, esperará a que pegues la barra de direcciones después de la redirección (la entrada está oculta: ni la URL ni el token aparecen en el historial del shell), extraerá access_token, lo guardará en ~/.config/yandex-direct/token con permisos 600 y ejecutará inmediatamente una comprobación de acceso.

<CLIENT_ID> — el identificador de la aplicación para la que se aprobó la solicitud. El script lo recordará en config.json; a partir de entonces se puede ejecutar sin argumento.

Manualmente, lo mismo: abrir https://oauth.yandex.ru/authorize?response_type=token&client_id=<CLIENT_ID>, tomar el token de la barra de direcciones después de #access_token= (hasta &) y guardarlo en el archivo.

3. Comprobación

printf '%s\n' \
  '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2025-06-18","capabilities":{}}}' \
  '{"jsonrpc":"2.0","id":2,"method":"tools/call","params":{"name":"direct_status","arguments":{}}}' \
  | node server.js

O simplemente pregunta al agente: «comprueba el acceso a Direct». Una respuesta exitosa muestra el inicio de sesión, la moneda de la cuenta y el saldo de puntos.

Escollos con los que nos topamos

Por separado: no se debe pegar el token en el chat del agente, ya que quedará en el historial de la conversación. Para eso está save-token.sh con entrada oculta. Si aun así lo pegaste, revoca el acceso en id.yandex.ru/personal/data-access y obtén uno nuevo.

Herramientas

Configuración

~/.config/yandex-direct/config.json:

{
  "token": "",
  "client_id": "…",
  "client_login": "",
  "sandbox": false
}

El token se lee en cada llamada; después de reemplazarlo no es necesario reiniciar el servidor.

Orden de búsqueda del token: YANDEX_DIRECT_TOKEN → config.json → ~/.config/yandex-direct/token.

Límites y coste

Cada llamada consume puntos (Units); el saldo llega en la cabecera de la respuesta y se imprime en el encabezado del resultado. Un get normal cuesta unos 10 puntos; los informes son más caros. El límite diario depende de la cuenta (en un cliente normal, alrededor de 160 000, suficiente para trabajar en vivo con margen).

El método get devuelve como máximo 10 000 objetos a la vez; después, paginación mediante LimitOffset. Las pujas se especifican en microunidades: 30000000 = 30 ₽. El ReportName del informe debe ser único; de lo contrario, Direct devolverá un informe generado anteriormente.

Esquema de interacción

Fuente: docs/scheme.html — útil si necesitas tu propia versión de la imagen para la solicitud.

Licencia

MIT — ver LICENSE.