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
MCP servers for Yandex APIs — Search, Wordstat, Webmaster, Metrika, Direct. 94 tools, Claude Code plugin included.
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.
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/[email protected]) 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 / 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 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).
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.
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):
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.
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:
Plugin
Manual MCP config
Setup
two commands
edit JSON, restart client
All five servers
registered at once
five entries, one per server
Paths
resolved via ${CLAUDE_PLUGIN_ROOT}
you hardcode absolute paths
Bundled skills
yandex-keyword-research, yandex-competitive-analysis installed too
not included — skills are Claude Code only
Updates
/plugin update yandex-mcp@stufently
git pull and re-check your paths
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:
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:
-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):
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:
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:
"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)
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:
Code passes bun run lint and bun run test with no errors.
All tools return both content (human-readable) and structuredContent (raw API data).
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.
API requests use fetchWithRetry with exponential backoff for 429/5xx errors.
Dates are validated with strict calendar checking (no silent overflow) in UTC.
Tokens are never printed to stdout in full.
License
MIT
Y
Yandex
stufently·20 estrellas·
MCP servers for Yandex APIs — Search, Wordstat, Webmaster, Metrika, Direct. 94 tools, Claude Code plugin included.
Aún no hay lista de herramientas. Los servidores remotos la reciben tras la primera comprobación de estado.
Preguntas frecuentes
Preguntas
¿Cómo instalo Yandex?
Copia en esta página la configuración stdio para Cursor, Claude Desktop, Claude Code o VS Code. Usa la instalación del publicador, no un proxy de PlugMCP.
¿Yandex necesita una clave de API?
El publicador indica estas variables de entorno: YANDEX_WEBMASTER_TOKEN.
¿Qué transporte usa Yandex?
Yandex se ejecuta localmente por stdio.
¿Cuándo se comprobó Yandex por última vez?
Última comprobación: 2026-11-15. MCP servers for Yandex APIs — Search, Wordstat, Webmaster, Metrika, Direct. 94 tools, Claude Code plugin included.