Yandex MCP Server

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

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, 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.

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:

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 is a documented config that nobody has checked end to end.

Client Configuration

Every block registers all five servers; drop the ones you do not need. Values are placeholders — see 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).

{
  "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:

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 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.

{
  "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:

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):

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

Cursor

yandex-search

yandex-wordstat

yandex-webmaster

yandex-metrika

yandex-direct

Each button installs one server; replace the your-… placeholders in ~/.cursor/mcp.json afterwards. Or add the block below by hand.

File: ~/.cursor/mcp.json (all projects) or .cursor/mcp.json (one project).

{
  "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"
      }
    }
  }
}

Windsurf

File: mcp_config.json — macOS and Linux ~/.config/devin/mcp_config.json (or $XDG_CONFIG_HOME/devin/mcp_config.json), Windows %APPDATA%\devin\mcp_config.json. Older builds used ~/.codeium/windsurf/mcp_config.json; that path is not in the current docs.

{
  "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"
      }
    }
  }
}

Zed

File: settings.json (command palette: zed: open settings file). The key is context_servers, not mcpServers.

{
  "context_servers": {
    "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"
      }
    }
  }
}

Codex

From the shell:

codex mcp add yandex-webmaster --env YANDEX_WEBMASTER_TOKEN=your-oauth-token \
  -- npx -y @stufently/yandex-webmaster-mcp

Or all five in ~/.codex/config.toml:

[mcp_servers.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" }

[mcp_servers.yandex-wordstat]
command = "npx"
args = ["-y", "@stufently/yandex-wordstat-mcp"]
env = { WORDSTAT_API_KEY = "your-cloud-api-key", WORDSTAT_FOLDER_ID = "your-folder-id" }

[mcp_servers.yandex-webmaster]
command = "npx"
args = ["-y", "@stufently/yandex-webmaster-mcp"]
env = { YANDEX_WEBMASTER_TOKEN = "your-oauth-token" }

[mcp_servers.yandex-metrika]
command = "npx"
args = ["-y", "@stufently/yandex-metrika-mcp"]
env = { YANDEX_METRIKA_TOKEN = "your-oauth-token" }

[mcp_servers.yandex-direct]
command = "npx"
args = ["-y", "@stufently/yandex-direct-mcp"]
env = { YANDEX_DIRECT_TOKEN = "your-oauth-token" }

Other ways to install

Claude Code plugin

This repo ships as a Claude Code plugin, so you do not have to hand-write five MCP entries. Add the repo as a marketplace and install:

/plugin marketplace add stufently/yandex-mcp
/plugin install yandex-mcp@stufently

Or without the interactive picker:

claude plugin marketplace add stufently/yandex-mcp
claude plugin install yandex-mcp@stufently --scope user

What the plugin gives you over a hand-written MCP config:

The plugin installs the servers but not the credentials — Claude Code substitutes only ${CLAUDE_PLUGIN_ROOT}, ${CLAUDE_PLUGIN_DATA} and ${CLAUDE_PROJECT_DIR}. Supply the Yandex tokens yourself, either by exporting them in your shell or by putting them in ~/.claude/settings.json:

{
  "env": {
    "YANDEX_SEARCH_API_KEY": "...",
    "YANDEX_FOLDER_ID": "...",
    "WORDSTAT_API_KEY": "...",
    "WORDSTAT_FOLDER_ID": "...",
    "YANDEX_WEBMASTER_TOKEN": "...",
    "YANDEX_METRIKA_TOKEN": "...",
    "YANDEX_DIRECT_TOKEN": "..."
  }
}

Servers whose variables are missing simply fail on first use; the rest keep working, so you can install the plugin and set up one API at a time.

Docker

The image ghcr.io/stufently/yandex-mcp is published with the next release tag; until then, build it from a clone with docker build -t yandex-mcp ..

One image holds all five servers. The first argument picks the server — search, wordstat, webmaster (the default), metrika or direct — and anything after it goes to the server. Keep -i (MCP talks over stdin) and pass the tokens with -e:

docker run -i --rm -e YANDEX_WEBMASTER_TOKEN ghcr.io/stufently/yandex-mcp webmaster
docker run -i --rm -e YANDEX_DIRECT_TOKEN ghcr.io/stufently/yandex-mcp direct

In a client config, Docker replaces npx. For example, Metrika in Claude Desktop:

{
  "mcpServers": {
    "yandex-metrika": {
      "command": "docker",
      "args": ["run", "-i", "--rm", "-e", "YANDEX_METRIKA_TOKEN", "ghcr.io/stufently/yandex-mcp", "metrika"],
      "env": { "YANDEX_METRIKA_TOKEN": "your-oauth-token" }
    }
  }
}

-e NAME without a value forwards the variable from the client's environment, so the token stays out of args. The image runs as the unprivileged node user, and the entrypoint execs the server, so docker stop reaches Node directly. The Wordstat fallback file ~/.config/yandex-cloud/wordstat.env is not visible inside the container — pass WORDSTAT_API_KEY and WORDSTAT_FOLDER_ID with -e. The OAuth helper prints a link and reads the code from stdin, so it works too: docker run -it --rm -e YANDEX_CLIENT_ID -e YANDEX_CLIENT_SECRET ghcr.io/stufently/yandex-mcp webmaster auth.

From source

Needs Node.js >= 22 and Bun on your PATH (the plugin needs Bun too: the repo carries a bun.lock, so Claude Code installs the plugin's dependencies with Bun and does not fall back to npm).

git clone https://github.com/stufently/yandex-mcp.git
cd yandex-mcp
bun install
cp .env.example .env   # then fill it in

For Webmaster and Metrika you can mint an OAuth token with the built-in flow (needs YANDEX_CLIENT_ID / YANDEX_CLIENT_SECRET from your own Yandex OAuth app):

node packages/yandex-webmaster-mcp/src/index.mjs auth
node packages/yandex-metrika-mcp/src/index.mjs auth

Search and Wordstat do not use OAuth: both talk to Yandex Cloud and need a service-account API key plus a folder ID.

The Metrika helper requests metrika:read metrika:write, because create-counter and delete-counter are refused with HTTP 403 by a read-only token. To keep a token that cannot modify anything, narrow the scope explicitly:

YANDEX_METRIKA_SCOPE="metrika:read" node packages/yandex-metrika-mcp/src/index.mjs auth

The two write tools then fail with a 403 that names the missing scope, instead of a bare permission error.

A write-capable token does not mean an unguarded delete: delete-counter refuses unless the call passes confirm: true, and the refusal happens before any request reaches Yandex. See Deleting a counter.

The same rule holds across the monorepo: an operation that cannot be undone through the API it is called with asks for confirm: true first — delete-counter in Metrika, delete-host in Webmaster, and the fourteen delete/update/bid tools in Direct. Additive and reversible writes (create-counter, add-host, add_*, archive and suspend) run without one, so the confirmation stays a signal rather than a reflex. Search and Wordstat are read-only and have nothing to guard.

To use a clone with any client block above, replace the npx command with node and the script path, e.g. for Webmaster:

"command": "node",
"args": ["/path/to/yandex-mcp/packages/yandex-webmaster-mcp/src/index.mjs"]

Inside a clone, the checked-in .mcp.json already registers all five servers for Claude Code from .env, with paths relative to the repo root.

Environment Variables

Copy .env.example to .env and fill in the values:

cp .env.example .env

You only need the variables for the servers you actually enable — each server reads its own and ignores the rest.

Example prompts

• Why did my site lose clicks last week?
• Which search phrases send the most visits to example.com?
• How many people search for this phrase on Yandex each month, and is that demand growing?
• Pause the Direct campaign that spent the most yesterday, then show me its new state.

Common Prompts

Once a server is connected, these are the kinds of requests it can answer. Each example maps onto real tools listed in the per-package READMEs.

yandex-search (1 tool)

• "Search Yandex for «купить кондиционер» and show me the top 10 results with their domains."
• "Who ranks on Yandex for «доставка пиццы» in region 2 (Saint Petersburg)? Give positions and titles."
• "Search yandex.ru for «отзывы о клинике» with strict family mode and pull 20 results."
• "Get page 2 of Yandex results for «ремонт ноутбуков Москва»."

yandex-wordstat (5 tools)

• "How many people search «купить ноутбук» on Yandex per month, and what related queries come up?"
• "Show the monthly trend for «горящие туры» over the last two years — is demand growing?"
• "Which Russian regions search «кондиционер» the most? Show volume and affinity index for the top 20."
• "Give me the Yandex region tree down to depth 2 so I can pick region IDs for filtering."
• "Compare desktop vs phone demand for «доставка еды»."

yandex-webmaster (33 tools)

• "List my verified sites in Yandex Webmaster with their SQI."
• "Add https://example.com/sitemap.xml to Webmaster for example.com."
• "Which pages dropped out of search on example.com recently, and why? Show anything that came back too."
• "Why did pages drop out of search on example.com? Group the samples by exclusion reason."
• "What are my top 50 queries by clicks for example.com, and how did positions move?"
• "Show indexing history for example.com and flag any sudden drop in pages in search."
• "What site problems does Yandex report for example.com right now?"
• "Send https://example.com/new-page for recrawl and tell me my remaining daily quota."
• "Show broken internal links on example.com — and say which of them Yandex has not re-checked in months."

yandex-metrika (12 tools)

• "Traffic summary for counter 12345678 last month — visits, users, bounce rate, average duration."
• "Where does my traffic come from? Break it down by source for counter 12345678."
• "Top 20 landing pages by pageviews for counter 12345678 last week."
• "Which countries and cities do my visitors come from?"
• "Custom report: ym:s:visits by ym:s:trafficSource and ym:s:deviceCategory for the last 7 days."

yandex-direct (43 tools)

• "List my active Yandex Direct campaigns with their types and states."
• "Show the keywords in campaign 123 together with their current search bids."
• "Build a last-30-days campaign performance report with impressions, clicks, and cost."
• "Pause campaign 123, then confirm its new state."
• "Pull the GeoRegions dictionary so I can pick targeting IDs."

Direct writes are live. Every write hits the production account — there is no dry-run. The fourteen that cannot be undone (delete_*, update_* and the three bid set_* tools) refuse unless the call passes confirm: true; add_*, archive_*/unarchive_*, suspend_*/resume_* and moderate_ads have an inverse tool and run straight away. Bids are expressed in micros (×10⁶). Set YANDEX_DIRECT_SANDBOX=true while experimenting. See Irreversible tools.

Skills

These are Claude Code skills, installed automatically with the plugin. They are not available to other MCP clients, which get the raw tools only.

yandex-keyword-research

Research keywords and search trends for Russian/CIS markets. Combines Wordstat data (volumes, trends, regional distribution) with Yandex Search results for a complete keyword analysis.

yandex-competitive-analysis

Analyze competitors and search landscape. Finds who ranks for target keywords, identifies content gaps, and discovers ranking opportunities across Russian/CIS markets.

Development

Requires Node.js >= 22.0.0 and Bun as the package manager.

# Install dependencies
bun install

# Lint
bun run lint

# Auto-fix lint issues
bun run lint:fix

# Format code
bun run format

# Unit tests (pure helpers: date windows, series extraction, XML parsing)
bun run test

# Smoke test: start every server over stdio and query tools/list
bun run smoke

# The same from the Docker image, with no credentials in the container
docker build -t yandex-mcp:local . && node scripts/docker-smoke.mjs yandex-mcp:local

Tech Stack

• Pure ES Modules (.mjs, no TypeScript, no build step)
• @modelcontextprotocol/sdk (^1.27.1)
• zod (^4.3.6) for input validation
• Biome for linting and formatting

Project Structure

packages/
  yandex-search-mcp/       # 1 tool   - Yandex Search  (src/parse.mjs — XML parsing)
  yandex-wordstat-mcp/     # 5 tools  - Keyword research (src/dates.mjs — API window rules)
  yandex-webmaster-mcp/    # 33 tools - Site analytics  (SKILL.md — agent playbook;
                           #                            src/series.mjs — time series shapes;
                           #                            src/exclusions.mjs — exclusion reasons)
  yandex-metrika-mcp/      # 12 tools - Web analytics
  yandex-direct-mcp/       # 43 tools - Ad campaigns
scripts/smoke-tools.mjs    # Starts every server and checks tools/list
scripts/docker-smoke.mjs   # Same check against the Docker image, without credentials
Dockerfile                 # One image for all five servers (docker/entrypoint.sh picks one)
.claude/skills/            # Claude Code skills (shipped with the plugin)
.mcp.json                  # Local dev config
plugin.mcp.json            # Distribution config — the 5 servers the plugin registers
.claude-plugin/
  plugin.json              # Plugin manifest
  marketplace.json         # Marketplace catalog, so the repo can be added directly

Each package keeps its pure, testable helpers in separate modules next to index.mjs; tests live in packages/*/test/*.test.mjs and run without network access.

Contributing

Contributions are welcome. Please ensure:

1. Code passes bun run lint and bun run test with no errors.
2. All tools return both content (human-readable) and structuredContent (raw API data).
3. The content text must not contradict structuredContent — a summary that reports "0 data points" while the structured payload holds a full series is a bug, and was the most common one in this repo's history.
4. API requests use fetchWithRetry with exponential backoff for 429/5xx errors.
5. Dates are validated with strict calendar checking (no silent overflow) in UTC.
6. Tokens are never printed to stdout in full.

License

MIT