yandex-mcp

# Yandex MCP

A monorepo of MCP (Model Context Protocol) servers for Yandex APIs. Provides AI assistants with access to Yandex Search, Wordstat, Webmaster, Metrika, and Direct through a unified interface.

Built for Russian and CIS market analysis -- keyword research, search analytics, site monitoring, web traffic insights, and ad campaign management.

## Packages

| Package | Description | Tools |
|---------|-------------|-------|
| [yandex-search-mcp](packages/yandex-search-mcp) | Yandex Search API v2 (Cloud) | 1 |
| [yandex-wordstat-mcp](packages/yandex-wordstat-mcp) | Yandex Wordstat (Cloud Search API v2) -- keyword research | 5 |
| [yandex-webmaster-mcp](packages/yandex-webmaster-mcp) | Yandex Webmaster API v4 -- site analytics | 33 |
| [yandex-metrika-mcp](packages/yandex-metrika-mcp) | Yandex Metrika API -- web analytics | 12 |
| [yandex-direct-mcp](packages/yandex-direct-mcp) | Yandex Direct API v5 -- ad campaigns | 43 |

**94 tools total** across all packages (counted by `node scripts/smoke-tools.mjs`).

> **Package names.** The packages go to npm under the **`@stufently/*` scope**
> (`@stufently/yandex-webmaster-mcp` and so on), starting with v2.2.0. The *unscoped* names — `yandex-search-mcp`,
> `yandex-wordstat-mcp`, `yandex-webmaster-mcp`, `yandex-metrika-mcp` — belong to a
> **different publisher** on the public registry (`altrr2`,
> [altrr2/yandex-tools-mcp](https://github.com/altrr2/yandex-tools-mcp), first published
> 2025-12-20, three months before this repo existed). Never `npx` an unscoped name with your
> Yandex tokens in the environment: that hands your credentials to unrelated code. Always type
> the `@stufently/` prefix.

## Install

Paste this into a terminal. It starts the Webmaster server on stdin; the same `npx` command is what every client block below runs.

```bash
YANDEX_WEBMASTER_TOKEN=your-oauth-token npx -y @stufently/yandex-webmaster-mcp
```

**Node.js >= 22** is the only prerequisite — no clone, no Bun, no build step. Swap the package and the variables for another server:

| Server | Command | Variables it needs |
|---|---|---|
| Search | `npx -y @stufently/yandex-search-mcp` | `YANDEX_SEARCH_API_KEY`, `YANDEX_FOLDER_ID` |
| Wordstat | `npx -y @stufently/yandex-wordstat-mcp` | `WORDSTAT_API_KEY`, `WORDSTAT_FOLDER_ID` |
| Webmaster | `npx -y @stufently/yandex-webmaster-mcp` | `YANDEX_WEBMASTER_TOKEN` |
| Metrika | `npx -y @stufently/yandex-metrika-mcp` | `YANDEX_METRIKA_TOKEN` |
| Direct | `npx -y @stufently/yandex-direct-mcp` | `YANDEX_DIRECT_TOKEN` (+ optional `YANDEX_DIRECT_CLIENT_LOGIN`, `YANDEX_DIRECT_SANDBOX`) |

All five servers start without their variables and fail only on the first tool call, with an
error that names the missing variable.

Append a version (`@stufently/yandex-webmaster-mcp@2.2.1`) to pin it instead of taking the
latest release on every start. The OAuth helper runs the same way:
`npx -y @stufently/yandex-webmaster-mcp auth` (and `@stufently/yandex-metrika-mcp auth`).

Do not `npx` the **unscoped** names — they belong to a different publisher (see the note
above).

## Verified clients and platforms

Only what has actually been run is listed as verified. Everything else in
[Client Configuration](#client-configuration) is a documented config that nobody has
checked end to end.

| Client / runtime | OS | How it runs | Status | Evidence |
|---|---|---|---|---|
| Claude Code 2.1 | Ubuntu 26.04 LTS, x86_64 | Node.js 24 from a checkout, stdio: `yandex-direct`, `yandex-wordstat`, `yandex-webmaster` | Verified | Daily use on the maintainer's host |
| Codex CLI 0.162 | Ubuntu 26.04 LTS, x86_64 | Node.js 24 from a checkout: `yandex-wordstat`, `yandex-webmaster` | Configured, not checked separately | Maintainer's host config |
| Node.js 22 + Bun | Ubuntu (`ubuntu-latest`) | Unit tests; all five servers answer `tools/list` over stdio | Verified in CI | `ci.yml` (`node --test`, `scripts/smoke-tools.mjs`) |
| `yandex-metrika`, `yandex-search` with a real token | any | — | Not verified in a client | CI smoke test only |
| `npx @stufently/*` from npm | Ubuntu, `node:24-alpine` | `npx -y @stufently/yandex-*-mcp`, stdio | Verified | All five answer `tools/list` from the published 2.2.0 packages (2026-10-15) |
| Claude Desktop (`.mcpb`), Claude Code plugin | any | Desktop Extension, plugin | Not verified | Bundles are built in CI, never installed in a real Desktop or as a plugin |
| Cursor, Windsurf, Zed | any | Configs below | Not verified | Documented only |
| macOS, Windows | — | Any client | Not verified | No CI runner on these systems |

## Client Configuration

Every block registers all five servers; drop the ones you do not need. Values are placeholders —
see [Environment Variables](#environment-variables) for where each one comes from. `command` is
the same `npx` as in the terminal snippet above.

### Claude Code

Project file: `.mcp.json` in the project root (Claude Code also reads a user-level config; this block is the project file).

```json
{
  "mcpServers": {
    "yandex-search": {
      "command": "npx",
      "args": ["-y", "@stufently/yandex-search-mcp"],
      "env": {
        "YANDEX_SEARCH_API_KEY": "your-cloud-api-key",
        "YANDEX_FOLDER_ID": "your-folder-id"
      }
    },
    "yandex-wordstat": {
      "command": "npx",
      "args": ["-y", "@stufently/yandex-wordstat-mcp"],
      "env": {
        "WORDSTAT_API_KEY": "your-cloud-api-key",
        "WORDSTAT_FOLDER_ID": "your-folder-id"
      }
    },
    "yandex-webmaster": {
      "command": "npx",
      "args": ["-y", "@stufently/yandex-webmaster-mcp"],
      "env": { "YANDEX_WEBMASTER_TOKEN": "your-oauth-token" }
    },
    "yandex-metrika": {
      "command": "npx",
      "args": ["-y", "@stufently/yandex-metrika-mcp"],
      "env": { "YANDEX_METRIKA_TOKEN": "your-oauth-token" }
    },
    "yandex-direct": {
      "command": "npx",
      "args": ["-y", "@stufently/yandex-direct-mcp"],
      "env": {
        "YANDEX_DIRECT_TOKEN": "your-oauth-token",
        "YANDEX_DIRECT_CLIENT_LOGIN": "",
        "YANDEX_DIRECT_SANDBOX": "true"
      }
    }
  }
}
```

Or from the terminal, one server at a time:

```bash
claude mcp add yandex-search --scope user \
  --env YANDEX_SEARCH_API_KEY=your-cloud-api-key --env YANDEX_FOLDER_ID=your-folder-id \
  -- npx -y @stufently/yandex-search-mcp
claude mcp add yandex-wordstat --scope user \
  --env WORDSTAT_API_KEY=your-cloud-api-key --env WORDSTAT_FOLDER_ID=your-folder-id \
  -- npx -y @stufently/yandex-wordstat-mcp
claude mcp add yandex-webmaster --scope user \
  --env YANDEX_WEBMASTER_TOKEN=your-oauth-token \
  -- npx -y @stufently/yandex-webmaster-mcp
claude mcp add yandex-metrika --scope user \
  --env YANDEX_METRIKA_TOKEN=your-oauth-token \
  -- npx -y @stufently/yandex-metrika-mcp
claude mcp add yandex-direct --scope user \
  --env YANDEX_DIRECT_TOKEN=your-oauth-token \
  -- npx -y @stufently/yandex-direct-mcp
```

Check with `claude mcp list`. The [plugin](#claude-code-plugin) does the same in two commands
and also installs the bundled skills.

### Claude Desktop

File: `claude_desktop_config.json` — macOS `~/Library/Application Support/Claude/claude_desktop_config.json`, Windows `%APPDATA%\Claude\claude_desktop_config.json`, Linux `~/.config/Claude/claude_desktop_config.json`.

```json
{
  "mcpServers": {
    "yandex-search": {
      "command": "npx",
      "args": ["-y", "@stufently/yandex-search-mcp"],
      "env": {
        "YANDEX_SEARCH_API_KEY": "your-cloud-api-key",
        "YANDEX_FOLDER_ID": "your-folder-id"
      }
    },
    "yandex-wordstat": {
      "command": "npx",
      "args": ["-y", "@stufently/yandex-wordstat-mcp"],
      "env": {
        "WORDSTAT_API_KEY": "your-cloud-api-key",
        "WORDSTAT_FOLDER_ID": "your-folder-id"
      }
    },
    "yandex-webmaster": {
      "command": "npx",
      "args": ["-y", "@stufently/yandex-webmaster-mcp"],
      "env": { "YANDEX_WEBMASTER_TOKEN": "your-oauth-token" }
    },
    "yandex-metrika": {
      "command": "npx",
      "args": ["-y", "@stufently/yandex-metrika-mcp"],
      "env": { "YANDEX_METRIKA_TOKEN": "your-oauth-token" }
    },
    "yandex-direct": {
      "command": "npx",
      "args": ["-y", "@stufently/yandex-direct-mcp"],
      "env": {
        "YANDEX_DIRECT_TOKEN": "your-oauth-token",
        "YANDEX_DIRECT_CLIENT_LOGIN": "",
        "YANDEX_DIRECT_SANDBOX": "true"
      }
    }
  }
}
```

One click, without editing JSON: download the `.mcpb` file for the server you want from
https://github.com/stufently/yandex-mcp/releases/latest and open it. Claude Desktop installs
the extension and asks for the token. Each server is its own file (`yandex-search-mcp`,
`yandex-wordstat-mcp`, `yandex-webmaster-mcp`, `yandex-metrika-mcp`, `yandex-direct-mcp`).
That path works before the npm packages are published. `YANDEX_DIRECT_SANDBOX` set to `true`
points Direct at the sandbox; leave it false for real campaigns. Restart the app after a manual edit.

Each release includes `checksums.txt` with the SHA256 checksum of every `.mcpb` bundle.
Download it alongside your bundle and verify the download before opening it:

```bash
sha256sum -c --ignore-missing checksums.txt   # run next to the downloaded .mcpb
```

Releases from the next tag on also carry a GitHub build provenance attestation for each
`.mcpb`, signed in the release workflow. Check that a bundle was built by this
repository's workflow and not swapped afterwards (needs the GitHub CLI):

```bash
gh attestation verify <bundle>.mcpb --repo stufently/yandex-mcp
```

### Cursor

[![Add yandex-search MCP server to Cursor](https://cursor.com/deeplink/mcp-install-dark.svg)](https://cursor.com/en/install-mcp?name=yandex-search&config=eyJjb21tYW5kIjoibnB4IiwiYXJncyI6WyIteSIsIkBzdHVmZW50bHkveWFuZGV4LXNlYXJjaC1tY3AiXSwiZW52Ijp7IllBTkRFWF9TRUFSQ0hfQVBJX0tFWSI6InlvdXItY2xvdWQtYXBpLWtleSIsIllBTkRFWF9GT0xERVJfSUQiOiJ5b3VyLWZvbGRlci1pZCJ9fQ%3D%3D) `yandex-search`

[![Add yandex-wordstat MCP server to Cursor](https://cursor.com/deeplink/mcp-install-dar