yandex-ultimate-mcp

# Yandex Ultimate MCP > 🇷🇺 **The main language is Russian.** English quick start is below.  <details><summary>Generated PNG cover</summary>  </details> **Yandex Ultimate MCP** — an unofficial “ultimate” MCP-gateway for the Yandex ecosystem. It does not copy code from other servers: it runs the best found open-source MCPs as child processes, collects their tools into one interface, adds `doctor`, `auth`-wizard, statuses, normal ENV-hints, and safe notices on licenses. ## 🚀 Auto-login and obtaining keys/tokens The fastest scenario: ```bash cd /Users/vlad/yandex-ultimate-mcp npm run auth npm run doctor npm run start ``` The Wizard now works as a route, not as “hold links”: 1. Raises a local callback: `http://127.0.0.1:17893/callback`. 2. Opens the page for creating a Yandex OAuth app. 3. Shows what to insert into the OAuth app: - name: `Yandex Ultimate MCP` - type: `For accessing API or debugging` - manual redirect URI: `https://oauth.yandex.ru/verification_code` - optional auto-capture redirect URI: `http://127.0.0.1:17893/callback` - permissions: `metrika:read/write`, `direct:api`, Webmaster scopes, `tracker:read/write`. 4. You insert `ClientID` into the terminal. 5. The Wizard asks only about the optional localhost Redirect URI: - if **yes** — catches `access_token` itself through localhost; - if **no** — uses the official manual flow: you copy a URL like `https://oauth.yandex.ru/verification_code#access_token=...`. 6. If you see `400 redirect_uri does not match`, it means there is no selected Redirect URI in the OAuth app: use manual mode or add an exact localhost URI. 7. The token is laid out in: - `YANDEX_TOKEN` - `YANDEX_METRIKA_TOKEN` - `YANDEX_DIRECT_TOKEN` - `YANDEX_WEBMASTER_TOKEN` / `YANDEX_WEBMASTER_OAUTH_TOKEN` - `YANDEX_TRACKER_TOKEN` 8. Then the wizard itself opens/suggests pages for Direct, Cloud/Search, and Maps keys. If you need Helium with your cookies: ```bash ULTIMATE_BROWSER_APP=Helium npm run auth ``` Important: `YANDEX_CLIENT_LOGIN` is not a token. This is the login of the client/account in Yandex Direct. If Direct is not needed, skip it. Webmaster usually uses the same OAuth token. If the OAuth app does not have Webmaster permissions or API access is limited to an account, `doctor` will show that the module did not turn on. Separately, you can get: - `YANDEX_TRACKER_ORG_ID` — id of the Tracker organization; - `YC_FOLDER_ID` / `YC_OAUTH_TOKEN` — Yandex Cloud; if `yc` is installed, the wizard will substitute `yc config list`; - `YANDEX_SEARCH_API_KEY` / `YANDEX_FOLDER_ID` — Yandex Cloud Search API for the current MCP; - Site search — a separate route: key in `developer.tech.yandex.ru` + connection to search on `site.yandex.ru`; - `YANDEX_MAPS_API_KEY` — Maps. > ⚠️ If the token accidentally got into chat, logs, or a screenshot — it's better to revoke it and issue a new one. If auto-opening the browser is not needed: ```bash ULTIMATE_NO_OPEN=1 npm run auth ``` ## What's inside | Module | What gives | Expected tools | Source | | --- | --- | ---: | --- | | `stegyan` | Direct + Metrika + Wordstat mega-pack | ~125 | [`@stegyan/yandex-mcp`](https://www.npmjs.com/package/@stegyan/yandex-mcp) | | `webmaster` | Webmaster: indexing, SQI, diagnostics, links, sitemap, recrawl | ~24 | [`yandex-webmaster-mcp`](https://www.npmjs.com/package/yandex-webmaster-mcp) | | `tracker` | Tracker issues/queues/comments/worklogs/users | ~21 | [`yandex-tracker-mcp`](https://www.npmjs.com/package/yandex-tracker-mcp) | | `cloud` | Cloud: Compute, VPC, Storage, PostgreSQL, AI, K8s, Serverless, Security | ~31 | [`yandex-cloud-mcp`](https://www.npmjs.com/package/yandex-cloud-mcp) | | `maps` | Geocode, reverse geocode, organizations, routes, static maps | ~10 | [`@theyahia/yandex-maps-mcp`](https://www.npmjs.com/package/@theyahia/yandex-maps-mcp) | | `search` | Yandex Cloud Search API bridge (`YANDEX_SEARCH_API_KEY` + `YANDEX_FOLDER_ID`) | ~1 | [`yandex-search-mcp`](https://www.npmjs.com/package/yandex-search-mcp) | | `cloud_docs` | Search/reading of Yandex Cloud documentation (optional, off by default) | ~11 | [`@doctorai/yandex-cloud-docs-mcp-server`](https://www.npmjs.com/package/@doctorai/yandex-cloud-docs-mcp-server) | Extras: - one MCP endpoint instead of a bunch of disparate servers; - auto-hiding modules without tokens, understandable `ultimate_status`; - `ultimate_auth_help`, `yandex-ultimate auth`, `.env.example`, and detailed `docs/AUTH.md`; - collision-safe tool names: if names intersect, the gateway will show `module__tool`; - `ULTIMATE_PREFIX_TOOLS=1`, if you want to always clearly see the source of the tool; - safe-by-default: secrets are not logged, `.env.local` in `.gitignore`; - MIT project + `THIRD_PARTY_NOTICES.md` for upstream MCP. ## Installation ```bash npm install -g yandex-ultimate-mcp # or without installation: npx yandex-ultimate-mcp@latest doctor ``` For development from the repository: ```bash git clone https://github.com/lemonchikHere/yandex-ultimate-mcp.git cd yandex-ultimate-mcp npm install cp .env.example .env.local npm run build npm run doctor ``` ## Connecting to the MCP client ### Codex / Claude Desktop / Cursor-style stdio ```json { "mcpServers": { "yandex-ultimate": { "command": "npx", "args": ["-y", "yandex-ultimate-mcp@latest", "serve"], "env": { "YANDEX_TOKEN": "...", "YANDEX_CLIENT_LOGIN": "...", "YANDEX_WEBMASTER_TOKEN": "...", "YANDEX_WEBMASTER_OAUTH_TOKEN": "...", "YANDEX_TRACKER_TOKEN": "...", "YANDEX_TRACKER_ORG_ID": "...", "YC_OAUTH_TOKEN": "...", "YC_FOLDER_ID": "...", "YANDEX_SEARCH_API_KEY": "...", "YANDEX_FOLDER_ID": "...", "YANDEX_MAPS_API_KEY": "..." } } } } ``` Locally from checkout: ```json { "mcpServers": { "yandex-ultimate-local": { "command": "node", "args": ["/ABS/PATH/yandex-ultimate-mcp/dist/src/cli.js", "serve"], "env": { "YANDEX_TOKEN": "..." } } } } ``` ## Quick auth ```bash yandex-ultimate auth # or npx yandex-ultimate-mcp@latest auth ``` The Wizard itself opens pages, uses the official manual OAuth flow or optional localhost auto-capture, pulls out `access_token`, catches `yc config list`, and writes `.env.local` without duplicates. Details: [`docs/AUTH.md`](docs/AUTH.md). ## Webmaster token / WEBMASTER_TOKEN For Yandex Webmaster OAuth app, it's better to create it like this: 1. Open the creation of OAuth application: https://oauth.yandex.ru/client/new 2. Name any, for example `Yandex Ultimate MCP`. 3. Application type: **For accessing API or debugging**. 4. Redirect URI for manual mode: `https://oauth.yandex.ru/verification_code`; localhost URI from wizard add only if auto-capture is needed. 5. In the **Data access** field, write `webmaster`. 6. In the appeared list, select **all 3 elements** Webmaster. 7. Create the application, copy `ClientID`, run `npm run auth`, and get a new token. 8. The Wizard will save it as `YANDEX_WEBMASTER_TOKEN` and `YANDEX_WEBMASTER_OAUTH_TOKEN`. If `get-user` returns `403 ACCESS_FORBIDDEN` and `application scopes: []`, it means the token was issued without Webmaster scopes — you need to reissue the token after selecting these accesses. ### Live Webmaster check `npm run doctor` now not only checks the presence of env but also makes a read-only request: ```text GET https://api.webmaster.yandex.net/v4/user Authorization: OAuth <token> ``` If you see `403 ACCESS_FORBIDDEN / application scopes: []`, the token was issued without Webmaster scopes — reissue it, selecting all 3 accesses `webmaster`. ## Yandex Search vs Site search Inside the gateway, `yandex-search-mcp` is currently connected — this is the **Yandex Cloud Search API**. For it, you need: ```env YANDEX_SEARCH_API_KEY=... YANDEX_FOLDER_ID=... ``` The documentation you found is **Yandex Site Search**: https://yandex.ru/dev/site/doc/ru/concepts/access There is a different path: 1. Get a key in the Developer Cabinet: https://developer.tech.yandex.ru/services/ 2. Select the `API Яндекс.Поиска для сайта` service. 3. Open `Мои поиски`: https://site.yandex.ru/ 4. In the selected search on the `Выдача в JSON` page, insert the API key. 5. Wait up to an hour until the changes take effect. Important: one Site Search key is connected to only one search. ## Module management ```bash # only Direct/Metrika/Wordstat + Webmaster ULTIMATE_ENABLE_MODULES=stegyan,webmaster yandex-ultimate-mcp serve # disable documentation directory ULTIMATE_DISABLE_MODULES=cloud_docs yandex-ultimate-mcp serve # always namespace-prefix ULTIMATE_PREFIX_TOOLS=1 yandex-ultimate-mcp serve ``` Management tools inside MCP: - `ultimate_status` — what's set up, what's enabled, what errors are in child MCP; - `ultimate_modules` — directory of modules/sources/licenses; - `ultimate_auth_help` — auth hints; - `ultimate_refresh_tools` — clear cache tools. ## Why gateway, not “copy everything to one server”? It's better legally and technically: - Upstream MCPs remain standalone packages with their own licenses; - Updates are pulled via `npx ...@latest`; - Less risk of breaking someone else's API implementation; - Easy replacement of a weak module with a more comprehensive one. We specifically **do not pull code** from packages with restrictive or unsuitable licenses. The list of sources and exceptions is in [`docs/SOURCES.md`](docs/SOURCES.md). ## Development ```bash npm install npm run build npm run smoke npm run audit npm run modules ``` Smoke test runs only management tools (`ULTIMATE_DISABLE_CHILDREN=1`), so CI doesn't require real tokens. --- # Tool List **Yandex Ultimate MCP** is an unofficial MCP gateway for the Yandex ecosystem. It aggregates existing open-source Yandex MCP servers behind one stdio endpoint and adds auth helpers, diagnostics, module controls and license notices. ```bash npm install -g yandex-ultimate-mcp yandex-ultimate-mcp doctor yandex-ultimate-mcp auth yandex-ultimate-mcp serve ``` Read [`docs/AUTH.md`](docs/AUTH.md) for tokens/API keys and [`THIRD_PARTY_NOTICES.md`](THIRD_PARTY_NOTICES.md) for upstream modules. ## License MIT for this gateway. Upstream MCP packages keep their own licenses and are executed as separate child processes.