How do I install Mutagen (mutagen.ru), Unofficial?

Copy the stdio config for Cursor, Claude Desktop, Claude Code, or VS Code on this page. It uses the publisher's install, not a PlugMCP proxy.

Does Mutagen (mutagen.ru), Unofficial need an API key?

The publisher lists these environment variables: MUTAGEN_API_KEY, MUTAGEN_BUDGET_RUB, MUTAGEN_AUTO_APPROVE_RUB, MUTAGEN_FREE_ONLY, MUTAGEN_TOOLS.

What transport does Mutagen (mutagen.ru), Unofficial use?

Mutagen (mutagen.ru), Unofficial runs locally over stdio.

When was Mutagen (mutagen.ru), Unofficial last checked?

Last checked 2026-11-09. Unofficial MCP server for the Mutagen SEO API: Wordstat frequencies, competition, semantic core

Mutagen (mutagen.ru), Unofficial MCP server

mutagen-ru-mcp

Неофициальный проект, не связан с Мутагеном. Данные принадлежат Мутагену (mutagen.ru).

Русский · English

Мутаген для нейросетей. mutagen-ru-mcp — MCP-сервер для Мутагена: Claude Code, Claude Desktop, Codex, Cursor, VS Code, Windsurf и другие MCP-клиенты получают частоты Вордстата, хвосты, конкуренцию, отчеты Мега-инструмента и готовые сценарии: «собери ядро за 20 ₽», «разложи фразы по страницам», «дай минус-слова для Директа». Перед каждым платным вызовом агент видит смету, а жесткий предел трат задаете вы.

Мутаген для кода. Тот же пакет — это CLI mutagen-ru и типизированная библиотека для Node.js. Ядро можно пересобирать по расписанию в GitHub Actions или cron, выгружать в CSV, XLSX и JSON, складывать в базу и получать pull request с новыми фразами раз в неделю. Кэш, журнал задач и лимит бюджета работают одинаково в MCP, CLI и библиотеке.

Быстрый старт

Нужен Node.js 22.12 или новее.

1. Ключ API

Зарегистрируйтесь на mutagen.ru (партнерская ссылка автора проекта; обычная регистрация — на https://mutagen.ru).
Возьмите ключ в кабинете: https://mutagen.ru/?api_config. Там же включите «Разрешить подключение только с ip» — API работает только по HTTP, см. ограничения.
Пополните баланс. Парсер Вордстата и проверка конкуренции списываются с баланса (от 0,02 ₽ за запрос). Отчеты Мега-инструмента через API доступны только с подпиской: тарифы.

2. Проверка

export MUTAGEN_API_KEY=ваш_ключ
npx -y -p mutagen-ru-mcp mutagen-ru balance

Баланс бесплатный. Если ответ пришел, ключ работает.

MCP-сервер запускается так: npx -y mutagen-ru-mcp. Обычно его запускает сам клиент, команда ниже уже вписана в конфиги.

3. Подключение к нейросети

Во всех примерах MUTAGEN_BUDGET_RUB — предел трат в рублях на весь процесс MCP-сервера (пока клиент его не перезапустит). Без него действует 50 ₽.

claude mcp add --env MUTAGEN_API_KEY=ваш_ключ --env MUTAGEN_BUDGET_RUB=50 \
  --transport stdio --scope user mutagen -- npx -y mutagen-ru-mcp

--scope user подключает сервер во всех проектах. Проверка: claude mcp get mutagen.

Файл claude_desktop_config.json (macOS: ~/Library/Application Support/Claude/, Windows: %APPDATA%\Claude\):

{
  "mcpServers": {
    "mutagen": {
      "command": "npx",
      "args": ["-y", "mutagen-ru-mcp"],
      "env": {
        "MUTAGEN_API_KEY": "ваш_ключ",
        "MUTAGEN_BUDGET_RUB": "50"
      }
    }
  }
}

После правки перезапустите Claude Desktop.

~/.codex/config.toml:

[mcp_servers.mutagen]
command = "npx"
args = ["-y", "mutagen-ru-mcp"]
startup_timeout_sec = 30   # первый запуск npx скачивает пакет
tool_timeout_sec = 120

[mcp_servers.mutagen.env]
MUTAGEN_API_KEY = "ваш_ключ"
MUTAGEN_BUDGET_RUB = "50"

Чтобы не хранить ключ в файле, замените таблицу env строкой env_vars = ["MUTAGEN_API_KEY"]: Codex передаст переменную из вашего окружения. Тот же сервер одной командой: codex mcp add mutagen --env MUTAGEN_API_KEY=ваш_ключ -- npx -y mutagen-ru-mcp.

.cursor/mcp.json в проекте или ~/.cursor/mcp.json для всех проектов:

{
  "mcpServers": {
    "mutagen": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "mutagen-ru-mcp"],
      "env": {
        "MUTAGEN_API_KEY": "${env:MUTAGEN_API_KEY}",
        "MUTAGEN_BUDGET_RUB": "50"
      }
    }
  }
}

${env:MUTAGEN_API_KEY} берет ключ из окружения, поэтому файл можно класть в git.

.vscode/mcp.json. VS Code спросит ключ при первом запуске и сохранит его в защищенном хранилище:

{
  "inputs": [
    {
      "type": "promptString",
      "id": "mutagen-key",
      "description": "Ключ API Мутагена (https://mutagen.ru/?api_config)",
      "password": true
    }
  ],
  "servers": {
    "mutagen": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "mutagen-ru-mcp"],
      "env": {
        "MUTAGEN_API_KEY": "${input:mutagen-key}",
        "MUTAGEN_BUDGET_RUB": "50"
      }
    }
  }
}

Файл mcp_config.json открывается из панели Cascade: меню ... → MCPs → Open MCP config file. Сейчас он лежит в ~/.config/devin/mcp_config.json (Windows: %APPDATA%\devin\mcp_config.json), в старых версиях Windsurf — в ~/.codeium/windsurf/mcp_config.json.

{
  "mcpServers": {
    "mutagen": {
      "command": "npx",
      "args": ["-y", "mutagen-ru-mcp"],
      "env": {
        "MUTAGEN_API_KEY": "${env:MUTAGEN_API_KEY}",
        "MUTAGEN_BUDGET_RUB": "50"
      }
    }
  }
}

Те же конфиги отдельными файлами лежат в examples/clients.

Сервер по HTTP. Для клиентов, которые подключаются по адресу, есть Streamable HTTP:

MUTAGEN_API_KEY=ваш_ключ npx -y mutagen-ru-mcp --http --port 3333
# адрес для клиента: http://127.0.0.1:3333/mcp

Если слушать не localhost (--host 0.0.0.0), обязателен токен MUTAGEN_MCP_HTTP_TOKEN: клиент передает его в заголовке Authorization: Bearer .... Запросы из браузера с заголовком Origin сервер принимает только с localhost; другие адреса перечислите через запятую в MUTAGEN_MCP_ALLOWED_ORIGINS. Бюджет MUTAGEN_BUDGET_RUB общий для всех HTTP-сессий процесса.

Что можно делать

Ниже — запросы, как их пишут в чате, инструменты, которые вызовет агент, и что получится. Ниша для примеров — натяжные потолки, регион Вордстата — Россия (225). Где написано «живой ответ», это настоящий результат запроса к Мутагену от 14.10.2026, сокращенный до первых строк. Где написано «пример», таблица показывает форму ответа, а цифры условные.

Цены взяты из живой проверки 14.10.2026: частота 0,02 ₽ за фразу и вид, «Ключи Вордстата» 0,02 ₽ (200 фраз) или 0,20 ₽ (2000 фраз), конкуренция 0,30 ₽ за фразу. Отчеты Мега-инструмента денег не списывают, но требуют подписку и расходуют суточную квоту запросов.

1. Собрать семантическое ядро для нового сайта или раздела

Собери семантическое ядро для раздела «натяжные потолки» по маркерам «натяжные потолки» и «потолки под ключ». Бюджет 15 рублей, регион Россия.

Агент: mutagen_build_core с dry_run: true → показывает смету → после вашего «да» тот же вызов без dry_run. Сценарий собирает хвосты маркеров, убирает дубли и явный мусор («скачать», «вакансии», «б/у» и т. п.), снимает точную частоту "!фраза" и группирует фразы в кластеры. MCP-prompt build-core ведет агента по этим шагам.

Смета — живой ответ --dry-run для двух маркеров:

Шаг	Метод	Единиц	Сумма
Хвосты маркеров (200 фраз)	`parser.get`, `wordstat_key_50`	2	0,04 ₽
Точная частота	`parser.mass.new`, `wordstat_qs`	500	10,00 ₽
Итого			10,04 ₽

Если бюджет меньше сметы, план уменьшается до бюджета: при 1,5 ₽ сценарий честно пишет «план уменьшен: max_phrases 500 → 73». Результат — таблица и файл (пример):

Фраза	Базовая частота	"!Точная"	Кластер	Маркер
натяжной потолок цена	55 926	1 011	натяжной потолок цена	натяжные потолки
сколько стоит натяжной потолок	18 667	1 382	сколько стоит натяжной потолок	натяжные потолки
…

Цена: по смете, не больше budget_rub. CLI: mutagen-ru core "натяжные потолки" "потолки под ключ" --budget 15 -o core.xlsx.

2. Расширить ядро хвостами и подсказками

Вот наше ядро (core.csv). Найди новые фразы, которых в нем еще нет, бюджет 5 рублей.

Агент: mutagen_expand_core (маркеры по умолчанию — главные фразы кластеров) или mutagen_wordstat_keywords по одной фразе. Живой ответ «Ключи Вордстата», 200 фраз, 0,02 ₽:

Фраза	Частотность
натяжной потолок	1 073 667
потолок под натяжной потолок	56 753
натяжной потолок цена	55 926
установка натяжных потолков	52 489
натяжные потолки фото	40 119
натяжной потолок своими руками	32 939
… еще 194 строки

С подпиской Мега-инструмента source: "serp" берет хвосты из базы Мутагена (report_keyword_tailings), без подписки — из Вордстата. source: "auto" выбирает сам. CLI: mutagen-ru keywords "натяжные потолки" --depth 200 -o tails.csv, mutagen-ru expand -i core.csv --budget 5.

3. Снять базовую и точную частоту, оценить конкуренцию

Сними базовую и точную частоту по этим четырем фразам. Потом проверь конкуренцию у двух самых частотных.

Агент: mutagen_frequency с types: ["wordstat_n", "wordstat_qs"], затем mutagen_competition. Живой ответ, 4 фразы × 2 вида = 0,16 ₽:

Фраза	Базовая	"!Точная"
натяжной потолок цена	62 529	1 011
установка натяжных потолков	54 907	593
натяжной потолок купить	27 870	694
сколько стоит натяжной потолок	20 422	1 382

Доступны все виды частотности Вордстата: базовая n, "фразовая" q, "!точная" qs, [порядок] no, "[порядок]" qo, "[!точный порядок]" qso. Конкуренция — шкала Мутагена 0–25 (ниже 5 — низкая), плюс частота в кавычках, число хвостов, ставки Директа и витальный сайт (пример):

Фраза	Конкуренция (0–25)	Частота "в кавычках"	Хвосты
натяжной потолок цена	12	4 800	950

Цена: частота 0,02 ₽ × фраза × вид, конкуренция 0,30 ₽ × фраза, повтор той же фразы в течение 7 дней бесплатный. Конкуренция зависит от связи Мутагена с Яндекс Директом и может считаться очень долго, см. ограничения. CLI: mutagen-ru freq -t n,qs -i phrases.txt, mutagen-ru competition -i top.txt.

4. Кластеризовать фразы и разложить их по страницам

Разложи фразы из tails.csv по страницам: какие фразы вести на одну страницу.

Агент: mutagen_cluster. Три режима:

lexical — бесплатно и без обращения к API: группировка по общим словам с учетом словоформ (стеммер Snowball);
serp — по совпадению URL в топе выдачи, как кластеризация на сайте Мутагена; нужна подписка, 1 запрос квоты на фразу, до 300 фраз;
project — забрать готовые кластеры проекта «Избранного» по его id (бесплатно).

Живой ответ, lexical, 40 фраз, бесплатно (сокращено):

Кластер	Фраза	Частота
натяжной потолок цена	натяжной потолок цена	55 926
натяжной потолок цена	стоимость натяжного потолка	11 164
натяжной потолок цена	натяжной потолок цена за м2	4 421
точечные светильники для натяжного потолка	точечные светильники для натяжного потолка	5 767
точечные светильники для натяжного потолка	встраиваемый светильник в натяжной потолок	3 499
натяжные потолки скрытый карниз	скрытый карниз в натяжном потолке	3 650

Лексическая группировка грубая: фразы с одинаковыми словами она объединяет, даже если интент разный (в живом прогоне «светильники» и «монтаж» попали в кластер «цена»). Для раскладки по страницам точнее режим serp. CLI: mutagen-ru cluster -i tails.csv, mutagen-ru cluster --mode serp -i tails.csv.

5. Выбрать Title, H1 и Description по частотам

Предложи Title, H1 и Description для страницы цен на натяжные потолки по этим фразам.

Агент: mutagen_title_h1. Если у фраз уже есть частоты, это бесплатно. Если нет, сценарий снимет точную частоту: 0,02 ₽ за фразу. Живой ответ на 15 фраз кластера «цена»:

Элемент	Текст	Обоснование
Title	Натяжной потолок цена — с установкой, за метр	главная фраза «натяжной потолок цена» (55 926) + хвосты фраз «потолок натяжной цена с установкой» (21 548) и «натяжной потолок цена за метр» (6 884)
H1	Потолок натяжной цена с установкой	вторая по частоте формулировка (21 548)
Description	Натяжной потолок цена: с установкой, за метр. Узнайте подробнее на сайте!	главная фраза + те же уточнения + призыв

Слова не склоняются: уточнения берутся целыми фразами кластера или их хвостами в том виде, в каком они есть в Вордстате, поэтому заготовка не собирает слова разных фраз в одну неграмотную группу. Город добавляется через запятую. Это заготовка с обоснованием по частотам, а не готовый текст: ее правит редактор. Параметры brand и city добавляют бренд и город. CLI: mutagen-ru title -i price.csv --city Москва.

6. Найти фразы, по которым нет страницы

Какие запросы конкурентов из топа есть у них и нет у нашего сайта example.ru?

С подпиской агент вызовет mutagen_content_gap: ключи вашего домена и 5 конкурентов (их Мутаген находит сам, или задайте competitors), разница — фразы, по которым у вас нет страницы. Цена: 1 запрос квоты на домен. Пример:

Фраза	Частота	Конкурентов	Лучшая позиция	Лучший конкурент
натяжной потолок в ванной	17 610	3	2	a.ru

Без подписки: выгрузите список фраз, под которые у вас уже есть страницы (pages.txt), и сравните его с ядром бесплатной локальной операцией:

mutagen-ru text compare -i pages.txt -i core.csv --implicit

Строки с only_b — фразы ядра без страницы. --implicit считает одинаковыми фразы, которые отличаются только формой слов или порядком.

7. Проверить позиции

На каких позициях example.ru по запросам про натяжные потолки?

Агент: mutagen_domain_report с report_keywords_organic (ключи и позиции домена) или mutagen_keyword_report с report_keyword_positions_organic (топ-50 по фразе). Нужна подписка, 1 запрос квоты. Пример (колонки отчета Мутагена):

keyword	position	region_wsn	page
натяжные потолки под ключ	7	3 100	https://example.ru/catalog/

Честно: это позиции из базы Мутагена, которую он обновляет периодически, а не съем выдачи в реальном времени. В API нет инструмента, который проверит позицию прямо сейчас. Бесплатной альтернативы внутри Мутагена нет. Позиции своего сайта можно смотреть в Яндекс Вебмастере.

8. Подготовить ядро для Директа: минус-слова

Подготовь минус-слова для кампании по натяжным потолкам.

Агент: mutagen_minus_words (MCP-prompt direct-prep). По готовому списку фраз — бесплатно, по маркерам — сначала собирает «Ключи Вордстата» (0,02 ₽ за маркер). Живой ответ на 200 фраз, бесплатно:

-своими -руками -видео -фото -как -сделать -самостоятельно -авито

Слово	Категория	Спорно	Фраз	Сумма частот
своими руками	Своими руками	нет	9	65 594
фото	Фото и видео	нет	3	45 175
работа	Работа и вакансии	да	1	9 173
отзывы	Отзывы и обсуждения (спорно)	да	1	7 130

Спорные слова в строку не попадают: решение за вами (include_disputed или --disputed добавит их). Ставки и прогноз Директа — mutagen_direct_bids, 0,02 ₽ за фразу, но сейчас этот сбор может идти очень долго, см. ограничения. CLI: mutagen-ru minus -i tails.csv, mutagen-ru minus "натяжные потолки" --budget 1.

9. Сравнить с конкурентами

Кто конкуренты example.ru в выдаче и по каким запросам они нас обходят?

Агент: mutagen_domain_report с report_domain_competitors (конкуренты по пересечению ключей), затем report_keywords_organic по конкуренту и mutagen_content_gap. Все это — отчеты Мега-инструмента: нужна подписка, 1 запрос квоты на отчет. Пример (колонки отчета Мутагена):

domain	visibility	domain_organic_keywords
a.ru	41,2	5 600

Без подписки: соберите ядро по маркерам, которые продвигает конкурент (mutagen_build_core), и сравните его со своим списком через mutagen_text с операцией compare.

10. Составить контент-план статей по ядру

Составь контент-план информационных статей по этим фразам.

Агент: mutagen_content_plan (MCP-prompt content-plan). По готовому списку — бесплатно: сценарий находит вопросы, группирует их и сортирует темы по сумме частот. По маркерам — сначала собирает фразы (с подпиской — хвосты-вопросы Мега-инструмента, без нее — Вордстат). Живой ответ на 200 фраз, бесплатно:

Тема статьи	Главный запрос	Сумма частот	Вопросов
Как снять натяжной потолок?	как снять натяжной потолок	154 372	26
Натяжной потолок сколько?	натяжной потолок сколько	55 783	3
Чем отмыть натяжной потолок?	чем отмыть натяжной потолок	10 198	2
Можно ли делать натяжной потолок?	можно ли делать натяжной потолок	2 376	1
Что сначала обои или натяжной потолок?	что сначала обои или натяжной потолок	2 282	1

Заголовки — черновые, их стоит переписать. Для выбранных тем агент может вызвать mutagen_title_h1. CLI: mutagen-ru plan -i tails.csv -o plan.xlsx.

Подключение к своим проектам

Все примеры лежат в examples/. Для CLI в CI и cron есть два важных флага: --yes подтверждает смету без вопроса (без него неинтерактивный запуск дороже 1 ₽ завершится с кодом 3) и --budget N ограничивает траты одного запуска.

Сбор по расписанию: GitHub Actions

examples/github-actions/weekly-core.yml — раз в неделю собирает ядро и сохраняет XLSX и отчет о тратах как артефакт сборки. Ключ хранится в секрете репозитория MUTAGEN_API_KEY.

- run: npm install --global mutagen-ru-mcp
- run: mutagen-ru core "натяжные потолки" --budget 20 --yes -o out/core.xlsx
  env:
    MUTAGEN_API_KEY: ${{ secrets.MUTAGEN_API_KEY }}
    MUTAGEN_BUDGET_RUB: "20"

Сбор по расписанию: cron

examples/cron/weekly-core.sh пишет ядро в файл с датой, строка для crontab -e — в examples/cron/crontab.txt:

0 6 * * 1  /path/to/weekly-core.sh >> /var/log/mutagen-core.log 2>&1

Выгрузка в CSV, XLSX, JSON

У любой команды CLI есть -o файл.csv|.xlsx|.json|.ndjson, у любого инструмента MCP — save_as. Файлы MCP ложатся только в каталог MUTAGEN_OUTPUT_DIR (по умолчанию ./mutagen-results): относительный save_as считается от него, путь наружу (.., ссылки) отклоняется. Существующий файл MCP не перезаписывает, а сохраняет результат рядом как «имя (2).csv»; заменить файл — overwrite: true. Только для stdio MUTAGEN_ALLOW_ANY_OUTPUT_PATH=1 разрешает любой путь. CSV рассчитан на русский Excel: разделитель «;», десятичная запятая, BOM, защита от формул в ячейках. В конце каждого файла есть строка «Данные: Мутаген (mutagen.ru)» (в XLSX — лист «Источник»): этого требуют условия API Мутагена.

mutagen-ru freq -t n,qs -i phrases.txt -o freq.xlsx
mutagen-ru keywords "натяжные потолки" --format json > tails.json

Google Таблицы

Есть два честных способа:

Разово. Файл → Импорт → Загрузка → core.csv, тип разделителя «Точка с запятой».
Автоматически. IMPORTDATA читает только CSV с запятыми или TSV по публичной ссылке. examples/google-sheets/to-sheets-csv.mjs переводит JSON-выгрузку CLI в CSV с запятыми. Положите его в публичный репозиторий или на любой публичный адрес и вставьте в ячейку:
```
=IMPORTDATA("https://raw.githubusercontent.com/SVorobiev-ru/REPO/main/semantic/core.sheets.csv")
```
Google Таблицы перечитывают файл сами, с задержкой. Файл из приватного репозитория так не открыть.

База данных

examples/db/to-sqlite.mjs складывает JSON-выгрузку в SQLite через встроенный node:sqlite (Node 22.13+ или 24), с датой сбора. По этой таблице легко смотреть историю частот:

mutagen-ru core "натяжные потолки" --budget 20 --yes -o core.json
node examples/db/to-sqlite.mjs core.json semantic.db

Скрипт на Node

Библиотека экспортирует то же, на чем работают CLI и MCP: клиент API (MutagenClient), сессию с бюджетом, кэшем и журналом (MutagenSession), сценарии (buildCore, expandCore, кластеризация, минус-слова и другие), локальную обработку фраз и выгрузку (writeTable). Полный пример — examples/node/build-core.mjs:

import { BudgetError, buildCore, loadConfig, MutagenSession, writeTable } from "mutagen-ru-mcp";

const session = MutagenSession.fromConfig(loadConfig()); // ключ и бюджет из переменных окружения
const params = { seeds: ["натяжные потолки"], budgetRub: 15 };

let result;
try {
  result = await buildCore(session, params);
} catch (error) {
  if (!(error instanceof BudgetError) || error.kind !== "needs_confirmation") throw error;
  // Смета выше MUTAGEN_AUTO_APPROVE_RUB: подтверждаем ее токеном из ошибки.
  result = await buildCore(session, params, { confirmToken: error.confirmToken });
}
await writeTable(result.table, "core.xlsx");

Агент, который раз в неделю обновляет ядро и открывает PR

examples/github-actions/weekly-core-pr.yml: CLI собирает ядро, бесплатная локальная команда mutagen-ru text compare сравнивает его с прошлым semantic/core.csv, новые фразы попадают в semantic/new-phrases.txt, и peter-evans/create-pull-request@v8 открывает PR с обновленным ядром. Вы смотрите diff и решаете, что взять.

Для этого в настройках репозитория включите Settings → Actions → General → Workflow permissions → «Allow GitHub Actions to create and approve pull requests».

Инструменты MCP и команды CLI

22 инструмента MCP и 18 команд CLI. Группа — значение для MUTAGEN_TOOLS.

Инструмент MCP	Команда CLI	Что делает	Цена	Группа
`mutagen_balance`	`balance`	Баланс аккаунта	бесплатно	basic
`mutagen_spending`	`spending`	Траты и остаток бюджета, журнал платных вызовов	бесплатно, локально	basic
`mutagen_estimate`	`estimate`	Смета плана вызовов	бесплатно, локально	basic
`mutagen_mass_tasks`	`mass list`	Массовые задания парсера	бесплатно	basic
`mutagen_mass_result`	`mass get <id>`	Результат массового задания	бесплатно	basic
`mutagen_project_keywords`	`projects <id>`	Ключи и кластеры проекта «Избранного»	бесплатно	basic
`mutagen_frequency`	`freq`	Частотность Вордстата, 6 видов, регион	0,02 ₽ × фраза × вид	parser
`mutagen_wordstat_keywords`	`keywords`	Левая колонка Вордстата: 200 или 2000 фраз	0,02 ₽ (200), 0,20 ₽ (2000)	parser
`mutagen_direct_bids`	`bids`	Ставки и прогноз Яндекс Директа	0,02 ₽ × фраза	parser
`mutagen_competition`	`competition`	Конкуренция 0–25 и статистика фразы	0,30 ₽ × фраза, повтор за 7 дней бесплатно	parser
`mutagen_keyword_report`	`report keyword <отчет> <фраза>`	Отчеты по фразе: статистика, хвосты, вопросы, вариации, LSI, топ-50, реклама	подписка, 1 запрос квоты	serp
`mutagen_domain_report`	`report domain <отчет> <домен>`

У платных инструментов MCP есть dry_run (только смета), confirm_token (подтверждение сметы), force_refresh (не брать из кэша), save_as и overwrite (сохранить в файл в MUTAGEN_OUTPUT_DIR, заменить существующий), fields и limit (сократить ответ). В CLI им соответствуют --dry-run, --yes, --refresh, -o, --limit. Справка по каждой команде: mutagen-ru <команда> --help.

Еще MCP-сервер отдает:

ресурсы mutagen://reference/reports (отчеты и колонки Мега-инструмента), mutagen://reference/regions (регионы), mutagen://reference/prices (цены методов и дата проверки);
prompts build-core, expand-core, direct-prep, content-plan — готовые сценарии для агента.

Коды выхода CLI: 0 — успех, 1 — ошибка API, 2 — неверные аргументы, 3 — нужно подтверждение сметы (--yes), 4 — превышен бюджет или включен режим «только бесплатное», 130 — прервано.

Как экономить

Смета до трат. --dry-run в CLI и dry_run: true в MCP показывают план и цену без обращения к API. mutagen_estimate и mutagen-ru estimate считают смету любого плана: mutagen-ru estimate --freq 500 -t n,qs --competition 50 → 35,00 ₽.
Лимит бюджета. MUTAGEN_BUDGET_RUB (по умолчанию 50 ₽) — жесткий предел трат на один запуск CLI или на весь процесс MCP-сервера: все его сессии, в том числе HTTP, тратят один общий бюджет до перезапуска. Вызов, который в него не помещается, отклоняется до обращения к API. --budget N в CLI ограничивает один запуск. Сценарии с бюджетом уменьшают план так, чтобы в него уложиться.
Порог подтверждения. Вызовы до MUTAGEN_AUTO_APPROVE_RUB (по умолчанию 1 ₽) идут без вопросов. Дороже — CLI спрашивает «Продолжить?» или ждет --yes, а MCP возвращает смету и confirm_token. Если клиент умеет спрашивать человека через свой интерфейс (elicitation), подтверждение спрашивается у вас.
Режим «только бесплатное». MUTAGEN_FREE_ONLY=1 или --free-only: любой платный вызов отклоняется, бесплатные (баланс, массовые задания, локальная обработка) работают.
Кэш. Готовые частоты и конкуренция хранятся 7 дней, отчеты Мега-инструмента — 1 день (MUTAGEN_CACHE_TTL_*_DAYS). Повторный запрос из кэша бесплатный. Баланс и статусы задач не кэшируются. Обойти кэш: --refresh или force_refresh, отключить: --no-cache или MUTAGEN_NO_CACHE=1.
Журнал и бесплатные повторы. Каждая платная задача пишется в журнал. Если ответ потерялся или задача еще считается, повтор того же вызова подхватывает уже оплаченную задачу и не платит второй раз. MCP ждет результат около 45 секунд, потом отвечает processing; повторите вызов позже — это бесплатно. Новую платную задачу вместо зависшей создает --new-task или new_task: true.
Меньше инструментов — меньше контекста. Описания и схемы всех 22 инструментов занимают около 34 тыс. символов контекста агента. MUTAGEN_TOOLS оставляет только нужные группы: например, basic,parser,text — около 14 тыс. символов. Группы: basic, parser, serp, scenarios, text.
Большие результаты — в файл. MCP отдает агенту сводку и первые строки, полный результат — в файл save_as. fields и убирают лишние колонки и строки, например 30 колонок прогноза Директа.

Настройки

Все настройки — переменные окружения. Пример — .env.example.

Переменная	По умолчанию	Что задает
`MUTAGEN_API_KEY`	—	Ключ API. Без него работают только локальные операции
`MUTAGEN_BUDGET_RUB`	`50`	Предел трат, ₽: на запуск CLI или на процесс MCP-сервера (общий для всех сессий)
`MUTAGEN_AUTO_APPROVE_RUB`	`1`	До этой суммы вызов идет без подтверждения, ₽
`MUTAGEN_FREE_ONLY`	`0`	`1` — отклонять любой платный вызов
`MUTAGEN_TOOLS`	все группы	Группы инструментов MCP: `basic,parser,serp,scenarios,text`
`MUTAGEN_OUTPUT_DIR`	`./mutagen-results`	Куда MCP сохраняет файлы; `save_as` не выходит за этот каталог
`MUTAGEN_ALLOW_ANY_OUTPUT_PATH`	`0`	`1` — `save_as` может указывать любой путь; только для stdio, по HTTP не действует
`MUTAGEN_MCP_WAIT_SECONDS`	`45`	Сколько вызов MCP ждет задачу Мутагена, прежде чем ответить `processing`
`MUTAGEN_MCP_HTTP_TOKEN`	—	Bearer-токен для `--http`; обязателен, если `--host` не localhost
`MUTAGEN_MCP_ALLOWED_ORIGINS`	—	Браузерные `Origin` через запятую, которым кроме localhost разрешен `--http`; без них запросы с `Origin` отклоняются
`MUTAGEN_CACHE_DIR`	`~/.cache/mutagen-ru-mcp`	Каталог кэша (Windows: `%LOCALAPPDATA%\mutagen-ru-mcp\cache`)
`MUTAGEN_STATE_DIR`	`~/.local/state/mutagen-ru-mcp`	Каталог журнала задач (Windows: `%LOCALAPPDATA%\mutagen-ru-mcp\state`)
`MUTAGEN_CACHE_TTL_FREQUENCY_DAYS`

Ограничения и честные оговорки

API только по HTTP. HTTPS у api.mutagen.ru нет, ключ уходит по сети открытым текстом в адресе запроса. Включите в кабинете белый список IP («Разрешить подключение только с ip»): тогда украденный ключ не сработает с чужого адреса. В наших логах, ошибках и файлах ключ заменяется на ***.
Отчеты Мега-инструмента — только по подписке. Хвосты из базы, вопросы, LSI, позиции, ключи сайтов и страниц, конкуренты, кластеризация по выдаче и поиск пробелов без подписки возвращают «нужна подписка» (ошибка 111). Вместе с ошибкой агент получает подсказку, чем заменить отчет без подписки.
Лимиты подписки. Отчеты расходуют суточную квоту запросов, а строки в отчете и выгрузки за месяц ограничены тарифом. По сайту на 14.10.2026: «Простой» — 950 ₽ в месяц, 300 запросов в сутки, 20 000 строк в отчете; «Расширенный» — 1 250 ₽, 1 500 запросов; «Продвинутый» — 2 450 ₽, 6 000 запросов. Актуально — на странице тарифов. Когда квота кончается, Мутаген отвечает ошибкой 112.
Нет списка проектов «Избранного». Метода в API нет, хотя он описан в документации. Ключи проекта доступны по id, а id берется из адреса страницы проекта в кабинете (Избранное → проект). Создавать проекты и добавлять в них ключи через API нельзя.
Нет правой колонки Вордстата. «Ключи Вордстата» отдают только левую колонку: 200 или 2000 фраз.
Конкуренция и ставки Директа могут висеть. Оба сбора зависят от связи Мутагена с Яндекс Директом. В октябре 2026 года они считались больше 40 минут. Деньги списываются при постановке задачи; повторный опрос бесплатный, и повтор того же вызова подхватывает уже оплаченную задачу. Если задача висит больше 2 часов, ответ прямо говорит о вероятном сбое на стороне Мутагена или Директа и советует проверить кабинет или написать в поддержку. Конкуренция считается без учета региона — так и на сайте Мутагена.
Частоты Вордстата приблизительны и меняются. Это оценка Яндекса, она плавает от месяца к месяцу. Разные способы сбора дают разные числа: в живой проверке «натяжной потолок цена» в левой колонке Вордстата — 55 926, а отдельным запросом базовой частоты — 62 529. Сравнивайте фразы, собранные одним способом.
Позиции — из базы Мутагена. Это не съем выдачи в реальном времени: база обновляется периодически.
Подтверждение через агента — защита от случайности, а не от злого умысла. Если клиент MCP не умеет спрашивать человека, confirm_token получает сам агент и может подтвердить смету без вас. Жесткий предел — только MUTAGEN_BUDGET_RUB. Ставьте его таким, какой не жалко потерять.
Функций сайта, которых нет в API, у нас тоже нет. Мы не автоматизируем веб-интерфейс Мутагена: только официальный API и локальная обработка. Рейтинги сайтов, создание проектов, кластеризация на стороне Мутагена недоступны.

FAQ

Это официальный клиент Мутагена? Нет. Это независимый проект с открытым кодом, он не связан с Мутагеном. Данные принадлежат Мутагену, в каждом ответе и файле стоит пометка «Данные: Мутаген (mutagen.ru)».

Нужна ли подписка? Для частот, «Ключей Вордстата», конкуренции, ставок Директа и всех локальных операций — нет, хватит баланса. Подписка нужна для отчетов Мега-инструмента: хвостов из базы, позиций, ключей сайтов, конкурентов, кластеризации по выдаче.

Сколько стоит собрать ядро? Два маркера, по 200 хвостов, точная частота для 500 фраз — 10,04 ₽. Проверка конкуренции для топ-20 фраз добавит 6 ₽. Точную смету для своих параметров покажет --dry-run.

Что работает без ключа? mutagen_text и mutagen-ru text, лексическая кластеризация, минус-слова и контент-план по готовому списку фраз, Title и H1 по фразам с частотами. Они не обращаются к API.

Агент может потратить все деньги? Не больше MUTAGEN_BUDGET_RUB за запуск CLI или за время работы MCP-сервера. Каждый вызов дороже MUTAGEN_AUTO_APPROVE_RUB требует подтверждения. Для полной уверенности включите MUTAGEN_FREE_ONLY=1.

Конкуренция ответила processing. Деньги списаны? Да, при постановке задачи. Повторите тот же вызов позже: он найдет задачу в журнале и не заплатит второй раз.

Почему частоты отличаются от того, что я вижу в Вордстате? Вордстат показывает оценку, которая меняется, а разные виды частотности и способы сбора дают разные числа. См. ограничения.

Как подключить к клиенту, которого нет в списке? Любой MCP-клиент со stdio запускает сервер командой npx -y mutagen-ru-mcp с переменной MUTAGEN_API_KEY. Клиентам, которые подключаются по адресу, подойдет npx -y mutagen-ru-mcp --http.

Участие в проекте

Ошибки, идеи и новые методы API — в issues. Как запустить проект, тесты и стиль коммитов — в CONTRIBUTING.md. Об уязвимостях — по SECURITY.md, не в открытых issue. Пожалуйста, никогда не публикуйте свой ключ API в issue и логах.

Лицензия

MIT. Проект неофициальный и не связан с Мутагеном. «Мутаген» и mutagen.ru принадлежат их владельцам. Данные, полученные через API, принадлежат Мутагену; условия их использования — в документации API и пользовательском соглашении.