/mutagen

name: mutagen
description: "[RU: интеграция mutagen.ru — частотность Яндекс, конкуренция, SERP-отчёты] Mutagen.ru REST API — RU SEO tool: точная частотность Yandex Wordstat, уровень конкуренции (strong), биды Директа, async check_key polling, parser.mass batch jobs, serp.report mega-tool with 22+ report types. Use when: mutagen, mutagen.ru, мутаген, api.mutagen.ru, точная частотность, частотность яндекс вордстат, конкуренция директа, mutagen.check_key, mutagen.parser.mass, mutagen.serp.report, mutagen.balance, claster_id, wordstat_qso, yandex_msk, yandex_spb, кластеризация семантики, SERP отчёт, биды директ, хвосты, упавшие фразы, parser_type, parser.mass polling, mass_id. SKIP: Yandex Wordstat direct API (→wordstat-api); Key Collector desktop (→key-collector); Topvisor/Rush Analytics/Serpstat (different SaaS); Ahrefs/Semrush (foreign SEO); Google Keyword Planner (Google data, Mutagen is Yandex-only)."
stacks:
  - mutagen
  - ru-seo
  - python
  - nodejs
tags:
  - seo
  - ru
  - keywords
  - wordstat
  - serp
  - mutagen
  - yandex
  - clustering
source: vechkasov-global-skills
risk: high-stakes

<!-- versions:start -->

🎯 Version Requirements (August 2026)

**Primary pins:**

• Mutagen API: `docs-only (stable JSON REST, no version path)`
• Python: `3.14.x`
• Node.js: `24.x (Active LTS)`

> Source of truth: [STACK_VERSIONS.md](../../STACK_VERSIONS.md) — verified 2026-08-24

<!-- versions:end -->

Usage

Loaded automatically when its description matches the active task. Read only the section you need, then follow the link to the relevant reference file for full detail.

Use this skill when

• Сбор семантики под Яндекс — массовая проверка точной частотности через `mutagen.parser.mass.new` (wordstat_qso для "[!фраза]")
• Проверка уровня конкуренции (`strong`) ключевых фраз через async `mutagen.check_key.new` + `mutagen.check_key.get` polling
• Получение биdов Яндекс.Директа (`direct.spec` / `direct.first` / `direct.garant`) для оценки стоимости трафика
• Парсинг левой колонки Вордстата — `wordstat_key` (до 2000 ключей, 10 страниц) или `wordstat_key_50` (первые 200 с первой страницы)
• SERP-анализ через `mutagen.serp.report` — конкуренты домена, упавшие/поднявшиеся фразы, хвосты, страницы домена, дополняющие фразы
• Region-specific data — yandex_msk, yandex_spb, yandex_minsk, yandex_nsk, yandex_ekb, yandex_rostov, yandex_kazan, yandex_nn
• Работа с проектами и `claster_id` — `mutagen.progects()` + `mutagen.progect.keywords(progect_id)` для кластеризации семантического ядра
• Building a Python/Node.js client с polling, idempotency, balance pre-check, deduplication, retry с exp backoff

Do not use this skill when

• Прямой парсинг Яндекс Wordstat без mutagen (own scraper, official Wordstat API) — use `wordstat-api` (cascade marker)
• Desktop tool Key Collector — use `key-collector` (cascade marker)
• Другие RU SEO-сервисы — Topvisor / Rush Analytics / SpyWords / Serpstat — different APIs, use their respective skills
• Foreign SEO SaaS — Ahrefs / Semrush / Moz / SE Ranking — use respective skills; Mutagen is Yandex-only RU domestic
• Google keyword data / Google Ads Keyword Planner — Mutagen returns ONLY Yandex data; for Google use different tooling
• Using the parsed keywords downstream in scraping / content generation — that belongs to the runtime skill (`httpx`, `nodejs`, `python`)

Purpose

Mutagen.ru is one of the dominant Russian SEO SaaS providers, used by SEO specialists, agencies, and content teams to collect Yandex semantic cores. Its core differentiator: cheap pay-per-call access to Wordstat exact-frequency variants (`wordstat_qso` = `"[!фраза]"`), proprietary competition metric (`strong`, scale ~1-25+), and a mega-tool `serp.report` covering 22+ report types — keyword info, organic positions, PPC bids, domain competitors, page-level analysis, lost/new/rising/falling keywords, и т.д.

This skill is **high-stakes** because every paid method debits the merchant balance per call, and incorrect polling/batching patterns burn money:

1. `check_key.new` creates a paid async task; calling it twice on the same keyword without persisting `task_id` doubles the spend. 2. `parser.mass.new` charges per keyword in the batch — not deduplicating means paying for duplicates. 3. `serp.report` with wrong `region` returns RU-wide data instead of city-specific, leading to wasted budget when re-running. 4. The async pattern (status: `created` → `processed` → `completed` | `rejected` | `error`) requires correct polling with exponential backoff — naive tight loops waste rate limits and create runaway poll storms. 5. UTF-8 is mandatory for Cyrillic keywords; wrong encoding silently corrupts data. 6. Public-service use requires attribution: *"Обязательным условием является размещении рядом с полученными через API данными информации о том, что они получены из Мутагена."*

The skill owns provider-domain knowledge — method shapes, parser-type semantics, region codes, filter/sort/count semantics, polling lifecycle, billing safety. HTTP plumbing belongs to the runtime skill (`httpx`, `nodejs`).

Using via mcp-mutagen

If you are working inside the **mcp-mutagen** MCP server, the raw Mutagen async API is already wrapped for you. Two tools are available:

• **`mutagen_api`** — generic gateway to the full Mutagen API: SERP reports (`serp.report` with all 23 report types), balance, projects, and keyword analytics. Handles async polling automatically. See [references/cookbook.md](references/cookbook.md) for ready-to-run recipes.
• **`mutagen_competition`** — convenience tool for batch keyword competition checks (`check_key`), with deduplication and 30-day caching built in.

Use `mutagen_competition` for batch competition scoring; use `mutagen_api` for everything else.

Tool signature

mutagen_competition({
  phrases: string[],          // required — one or more Russian search phrases
  poll_timeout_sec?: number,  // optional — max seconds to wait for results (default: 60)
  force_refre