# yandex-tools-mcp

MCP servers for Yandex APIs — search, keyword research, webmaster tools, and web analytics for the Russian market.

[English](#english) | [Русский](#русский)

---

## English

### Packages

| Package | Description | npm |
|---------|-------------|-----|
| [yandex-wordstat-mcp](./packages/yandex-wordstat-mcp) | Keyword research & search trends via the Yandex Wordstat **v2** API (Yandex Cloud) | [![npm](https://img.shields.io/npm/v/yandex-wordstat-mcp)](https://www.npmjs.com/package/yandex-wordstat-mcp) |
| [yandex-search-mcp](./packages/yandex-search-mcp) | Web search via Yandex Search API | [![npm](https://img.shields.io/npm/v/yandex-search-mcp)](https://www.npmjs.com/package/yandex-search-mcp) |
| [yandex-webmaster-mcp](./packages/yandex-webmaster-mcp) | Site analytics, indexing & SEO via Yandex Webmaster API | [![npm](https://img.shields.io/npm/v/yandex-webmaster-mcp)](https://www.npmjs.com/package/yandex-webmaster-mcp) |
| [yandex-metrika-mcp](./packages/yandex-metrika-mcp) | Web analytics & traffic data via Yandex Metrika API | [![npm](https://img.shields.io/npm/v/yandex-metrika-mcp)](https://www.npmjs.com/package/yandex-metrika-mcp) |
| [yandex-direct-mcp](./packages/yandex-direct-mcp) | PPC campaign management (campaigns, ads, keywords, bids, stats) via Yandex Direct API | [![npm](https://img.shields.io/npm/v/yandex-direct-mcp)](https://www.npmjs.com/package/yandex-direct-mcp) |

### Quick Start

**Yandex Wordstat v2** (keyword research) — Yandex Cloud Search API; uses the same key as Search:

```json
{
  "mcpServers": {
    "yandex-wordstat": {
      "command": "npx",
      "args": ["-y", "yandex-wordstat-mcp"],
      "env": {
        "YANDEX_SEARCH_API_KEY": "your_api_key",
        "YANDEX_FOLDER_ID": "your_folder_id"
      }
    }
  }
}
```

> Prefer a hosted tool? Use the managed endpoint at <a href="https://unoapi.ru/services/wordstat" target="_blank">unoapi.ru/services/wordstat</a> — no Yandex Cloud credentials to manage.

**Yandex Search** (web search):

```json
{
  "mcpServers": {
    "yandex-search": {
      "command": "npx",
      "args": ["-y", "yandex-search-mcp"],
      "env": {
        "YANDEX_SEARCH_API_KEY": "your_api_key",
        "YANDEX_FOLDER_ID": "your_folder_id"
      }
    }
  }
}
```

**Yandex Webmaster** (site analytics & SEO):

```json
{
  "mcpServers": {
    "yandex-webmaster": {
      "command": "npx",
      "args": ["-y", "yandex-webmaster-mcp"],
      "env": {
        "YANDEX_WEBMASTER_TOKEN": "your_oauth_token"
      }
    }
  }
}
```

**Yandex Metrica** (web analytics):

```json
{
  "mcpServers": {
    "yandex-metrika": {
      "command": "npx",
      "args": ["-y", "yandex-metrika-mcp"],
      "env": {
        "YANDEX_METRIKA_TOKEN": "your_oauth_token"
      }
    }
  }
}
```

**Yandex Direct** (PPC campaign management — defaults to sandbox; set `YANDEX_DIRECT_LIVE=1` for the real account):

```json
{
  "mcpServers": {
    "yandex-direct": {
      "command": "npx",
      "args": ["-y", "yandex-direct-mcp"],
      "env": {
        "YANDEX_DIRECT_TOKEN": "your_oauth_token"
      }
    }
  }
}
```

See individual package READMEs for detailed setup instructions.

Online usage example: <a href="https://seyka.ru" target="_blank">seyka.ru</a>

### Claude Code Plugin

Install all five MCPs as a single plugin with built-in skills for keyword research and competitive analysis:

```bash
# Set your API keys
export YANDEX_SEARCH_API_KEY=your_api_key   # also used by Wordstat
export YANDEX_FOLDER_ID=your_folder_id      # also used by Wordstat
export YANDEX_WEBMASTER_TOKEN=your_oauth_token
export YANDEX_METRIKA_TOKEN=your_oauth_token
export YANDEX_DIRECT_TOKEN=your_oauth_token  # defaults to sandbox

# Run with plugin
claude --plugin-dir /path/to/yandex-tools-mcp
```

**Included Skills:**
- `yandex-keyword-research` — Automatically triggered for keyword research, search volumes, and trend analysis
- `yandex-competitive-analysis` — Automatically triggered for competitor analysis and SERP research

---

## Русский

### Пакеты

| Пакет | Описание | npm |
|-------|----------|-----|
| [yandex-wordstat-mcp](./packages/yandex-wordstat-mcp) | Исследование ключевых слов через API Яндекс Вордстат **v2** (Yandex Cloud) | [![npm](https://img.shields.io/npm/v/yandex-wordstat-mcp)](https://www.npmjs.com/package/yandex-wordstat-mcp) |
| [yandex-search-mcp](./packages/yandex-search-mcp) | Веб-поиск через Yandex Search API | [![npm](https://img.shields.io/npm/v/yandex-search-mcp)](https://www.npmjs.com/package/yandex-search-mcp) |
| [yandex-webmaster-mcp](./packages/yandex-webmaster-mcp) | Аналитика сайта, индексация и SEO через Яндекс Вебмастер API | [![npm](https://img.shields.io/npm/v/yandex-webmaster-mcp)](https://www.npmjs.com/package/yandex-webmaster-mcp) |
| [yandex-metrika-mcp](./packages/yandex-metrika-mcp) | Веб-аналитика и данные о трафике через Яндекс Метрика API | [![npm](https://img.shields.io/npm/v/yandex-metrika-mcp)](https://www.npmjs.com/package/yandex-metrika-mcp) |
| [yandex-direct-mcp](./packages/yandex-direct-mcp) | Управление РРС-кампаниями (кампании, объявления, фразы, ставки, статистика) через API Яндекс Директа | [![npm](https://img.shields.io/npm/v/yandex-direct-mcp)](https://www.npmjs.com/package/yandex-direct-mcp) |

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

**Яндекс Вордстат v2** (исследование ключевых слов) — Yandex Cloud Search API; использует тот же ключ, что и Поиск:

```json
{
  "mcpServers": {
    "yandex-wordstat": {
      "command": "npx",
      "args": ["-y", "yandex-wordstat-mcp"],
      "env": {
        "YANDEX_SEARCH_API_KEY": "ваш_api_ключ",
        "YANDEX_FOLDER_ID": "ваш_folder_id"
      }
    }
  }
}
```

> Нужен готовый инструмент? Используйте размещённый эндпоинт <a href="https://unoapi.ru/services/wordstat" target="_blank">unoapi.ru/services/wordstat</a> — без необходимости управлять учётными данными Yandex Cloud.

**Яндекс Поиск** (веб-поиск):

```json
{
  "mcpServers": {
    "yandex-search": {
      "command": "npx",
      "args": ["-y", "yandex-search-mcp"],
      "env": {
        "YANDEX_SEARCH_API_KEY": "ваш_api_ключ",
        "YANDEX_FOLDER_ID": "ваш_folder_id"
      }
    }
  }
}
```

**Яндекс Вебмастер** (аналитика сайта и SEO):

```json
{
  "mcpServers": {
    "yandex-webmaster": {
      "command": "npx",
      "args": ["-y", "yandex-webmaster-mcp"],
      "env": {
        "YANDEX_WEBMASTER_TOKEN": "ваш_oauth_токен"
      }
    }
  }
}
```

**Яндекс Метрика** (веб-аналитика):

```json
{
  "mcpServers": {
    "yandex-metrika": {
      "command": "npx",
      "args": ["-y", "yandex-metrika-mcp"],
      "env": {
        "YANDEX_METRIKA_TOKEN": "ваш_oauth_токен"
      }
    }
  }
}
```

**Яндекс Директ** (управление РРС-кампаниями — по умолчанию песочница; установите `YANDEX_DIRECT_LIVE=1` для боевого аккаунта):

```json
{
  "mcpServers": {
    "yandex-direct": {
      "command": "npx",
      "args": ["-y", "yandex-direct-mcp"],
      "env": {
        "YANDEX_DIRECT_TOKEN": "ваш_oauth_токен"
      }
    }
  }
}
```

Подробные инструкции по настройке в README каждого пакета.

Онлайн пример использования: <a href="https://seyka.ru" target="_blank">seyka.ru</a>

### Плагин для Claude Code

Установите все пять MCP как единый плагин со встроенными навыками для исследования ключевых слов и анализа конкурентов:

```bash
# Установите API ключи
export YANDEX_SEARCH_API_KEY=ваш_api_ключ   # также используется Вордстатом
export YANDEX_FOLDER_ID=ваш_folder_id       # также используется Вордстатом
export YANDEX_WEBMASTER_TOKEN=ваш_oauth_токен
export YANDEX_METRIKA_TOKEN=ваш_oauth_токен
export YANDEX_DIRECT_TOKEN=ваш_oauth_токен  # по умолчанию песочница

# Запустите с плагином
claude --plugin-dir /path/to/yandex-tools-mcp
```

**Включённые навыки:**
- `yandex-keyword-research` — Автоматически активируется для исследования ключевых слов, объёмов поиска и анализа трендов
- `yandex-competitive-analysis` — Автоматически активируется для анализа конкурентов и исследования SERP

---

## Development

```bash
git clone https://github.com/altrr2/yandex-tools-mcp.git
cd yandex-tools-mcp
bun install
```

Lint and format:

```bash
bun run lint
bun run format
```

Publish packages:

```bash
cd packages/yandex-wordstat-mcp && npm publish
cd packages/yandex-search-mcp && npm publish
cd packages/yandex-webmaster-mcp && npm publish
cd packages/yandex-metrika-mcp && npm publish
cd packages/yandex-direct-mcp && npm publish
```

## License

MIT © Alternex