Mutagen

<!-- 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 — 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 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_refresh?: boolean,    // optional — bypass 30-day result cache (default: false)
})

What it returns

For each phrase: strong (competition score 1-25), wordstat (Wordstat frequency), direct.spec / direct.first / direct.garant (Yandex Direct bid estimates in RUB).

What it does automatically

• Submits check_key.new for each phrase, persists task_id internally.
• Polls check_key.get with exponential backoff until completed or timeout.
• Caches results for 30 days per phrase; repeated calls within TTL are free.
• Pass force_refresh: true to re-query and overwrite the cache.

Cost

~0.30 RUB per phrase. Results are cached 30 days, so repeating the same phrase within the TTL costs nothing. Before calling with a large list, verify your Mutagen balance — use mutagen.balance() directly (curl or a one-off script) or check your account dashboard at https://mutagen.ru/?api_config. A negative balance causes all tasks to be rejected.

Example

mutagen_competition({phrases: ["ремонт квартир москва", "купить машину"]})

Returns an array of two result objects, one per phrase, with strong, wordstat, and direct fields.

When to use raw API instead

Use the raw check_key.new + check_key.get pattern (documented below) when you need: custom polling timeouts, streaming partial results, or integration outside the mcp-mutagen runtime.

Capabilities

API client setup

Single endpoint pattern: http://api.mutagen.ru/json/{api_key}/{method}/?{params}. API key in the URL path (obtain at https://mutagen.ru/?api_config). UTF-8 required for all requests and source files. GET hard-limit 128KB — anything above MUST use POST with JSON-encoded params in body. Response envelope shape varies by method; status field carries lifecycle for async calls.

Full reference: references/setup.md

The method surface

Account: mutagen.balance (баланс). Projects/Избранное: mutagen.progects, mutagen.progect.keywords (with claster_id for кластеризация). Async competition: mutagen.check_key.new + mutagen.check_key.get. Parser: mutagen.parser.get (single) + mutagen.parser.mass.new/mass.list/mass.id (batch). SERP mega-tool: mutagen.serp.report (22+ report types × 9 regions × 17 filter types).

Full reference: references/methods.md

Async check_key pattern (state machine)

State flow: created → processed → completed | rejected | error. Poll check_key.get(task_id) with exponential backoff starting at 2-3 s capped at 30 s, max 60 attempts. While not completed, response mirrors check_key.new: {task_id, status}. On completed: returns key, strong (конкуренция), wordstat, tails, direct.{spec,first,garant} (ставки в Директе), vital, vital_site (тематический сайт). CRITICAL: persist task_id so retries on transient errors don't double-spend. rejected is terminal — re-submitting blindly re-charges.

Full reference: references/check-key-async-pattern.md

Parser types — Wordstat frequency variants

Nine parser types map to Wordstat modifier semantics: wordstat_n (broad, no quotes), wordstat_q ("" phrase match), wordstat_qs (!"" exact form), wordstat_no ([] order-locked), wordstat_qo ("[]"), wordstat_qso ("[!]" — точная частотность, эталон для SEO), wordstat_key (левая колонка Вордстата, до 2000 ключей, 10 страниц + правая колонка/ассоциации), wordstat_key_50 (первые 200 с первой страницы), direct (биды Директа со shows/bid1/bid2/bid3/all_positions). Picking the wrong variant gives wrong frequency and wastes budget.

Full reference: references/parser-types.md

SERP report — 22+ report types

mutagen.serp.report is a single endpoint switching on the report parameter. Keyword reports (require keyword / keywords CSV ≤1000): report_keyword_info, report_keyword_tailings (хвосты), report_keyword_variations, report_keyword_expansion (дополняющие фразы), report_keyword_positions_organic, report_keyword_positions_ppc. Domain reports: report_keywords_organic + _up/_down/_new/_lost (поднявшиеся/упавшие/новые/потерянные), report_keywords_ppc, report_keywords_ppc_history, report_domain_pages, report_domain_subdomains, report_domain_competitors, report_domain_competitors_ppc, report_domain_advert, report_domain_advert_active, report_domain_info. Page reports: report_page_info, report_page_competitors, report_page_recommended_keywords.

Full reference: references/serp-report.md

Filtering, sorting, row-count

17 filter types: gr (>), gr_or_eq (>=), less (<), less_or_eq (<=), eq (=), not_eq (!=), range (min+max numeric), in/not_in (CSV list up to 1024), like/not_like (substring), like_any/not_like_any (CSV up to 1024), like_start/like_finish (prefix/suffix), is (boolean). Combine with "or":1 marker to start an OR-block (default AND). Sort: "column" asc or "-column" desc, one column per request. count: 1 returns only {"count": N} — use for cheap row-count probes before paginating.

Full reference: references/filtering.md

Regions

For serp.report: nine region values — yandex_ru (global, keyword-only reports), yandex_msk, yandex_spb, yandex_minsk, yandex_nsk, yandex_ekb, yandex_rostov, yandex_kazan, yandex_nn. For parser methods: region_id="0" = no region (default); numeric region codes accepted as comma-separated list, - prefix excludes (e.g. "255,-17"). Mismatch between intended region and actual call returns useless data — region-specific frequency differs by orders of magnitude.

Full reference: references/regions.md

Pricing & balance safety

Mutagen is pay-per-call. mutagen.balance() returns current rubles. Documentation does NOT publish per-call costs in the API page — verify current tarification at https://mutagen.ru/?p=price. Pattern: always call mutagen.balance() before any paid batch and gate operation on balance >= expected_cost * 2. Track expected cost client-side (count of keys × known per-call rate from your account dashboard).

Full reference: references/pricing-and-balance.md

Batch strategy — parser.mass over loops

parser.mass.new accepts keys_list (array or CSV) with a name tag for tracking; returns {id, status}. Poll parser.mass.id(mass_id) until status: "finish". Always deduplicate keys_list before submit (case-fold + trim Cyrillic) — duplicates are charged. Single-shot parser.get is for one-off probes only; never loop over parser.get — use parser.mass.new for ≥2 keys.

Full reference: references/batch-strategy.md