Content
<p align="center">
<img src="resources/yandex-webmaster-mcp-server.jpg" alt="Yandex Webmaster MCP Server" />
</p>
# Yandex Webmaster MCP Server
[](https://www.npmjs.com/package/yandex-webmaster-mcp-server)
[](https://opensource.org/licenses/MIT)
MCP server for [Yandex Webmaster API v4](https://yandex.com/dev/webmaster/doc/dg/reference/host-id.html). Provides **46 tools** for managing sites, sitemaps, indexing, search analytics, backlinks, feeds, and more through Model Context Protocol.
## Capabilities
- **Core** --- user information, host management, verification, diagnostics
- **Content** --- sitemaps, indexing, URLs in search, important URLs, broken links, search events
- **Analytics** --- search queries, popular queries, external links, SQI, query analytics
- **Actions** --- page recrawling, original texts, feed management
### Prompt Examples
**Site Audit** --- quick site status and issue check:
- "What issues were detected on the site dellshop.ru?"
- "Are there any broken internal links on the site?"
- "Find pages excluded from search as low-value"
**Position Monitoring** --- tracking search visibility:
- "Show popular search queries for the last week"
- "Show SQI history for the last 3 months"
- "How many pages are indexed and what HTTP codes do they return?"
**Link Profile** --- external and internal link analysis:
- "What external links point to my site?"
- "Show external link dynamics for the last month"
**Actions** --- indexing and content management:
- "Resubmit the homepage for recrawl"
- "Show the list of all my sites in Yandex Webmaster"
## Installation
### Using npx (no installation)
```bash
npx -y yandex-webmaster-mcp-server
```
### Global Installation
```bash
npm install -g yandex-webmaster-mcp-server
yandex-webmaster-mcp-server
```
### From Sources
```bash
git clone https://github.com/weselow/yandex-webmaster-mcp-server.git
cd yandex-webmaster-mcp-server
pnpm install
pnpm build
```
## Configuration
### Environment Variables
| Variable | Required | Description |
|---|---|---|
| `YANDEX_WEBMASTER_OAUTH_TOKEN` | Yes | OAuth token for Yandex Webmaster API |
| `YANDEX_WEBMASTER_HOST_URL` | No | Default host URL (e.g., `https://example.com`) for reducing API calls |
### Obtaining OAuth Token
1. Go to [oauth.yandex.ru/client/new](https://oauth.yandex.ru/client/new)
2. Create an application:
- Enter a name (any, e.g., "Webmaster MCP")
- In the "Data Access" section, add permissions:
- `webmaster:verify` --- site verification
- `webmaster:hostinfo` --- access to site information
- Click "Create application"
- Copy the **ClientID** from the created application
3. Open the token retrieval link in your browser (substitute your ClientID):
```
https://oauth.yandex.ru/authorize?response_type=token&client_id=YOUR_CLIENT_ID
```
4. Authenticate and grant access to the application
5. Yandex will redirect you to a page with the token --- copy the **access_token** value from the address bar
6. Set the token in the `YANDEX_WEBMASTER_OAUTH_TOKEN` environment variable
## Usage
###_stdio Mode (default)
```bash
YANDEX_WEBMASTER_OAUTH_TOKEN=your-token npx -y yandex-webmaster-mcp-server
```
### HTTP Mode
```bash
YANDEX_WEBMASTER_OAUTH_TOKEN=your-token npx -y yandex-webmaster-mcp-server --http --port=3000
```
### Configuring MCP Client
For Claude Desktop or `.mcp.json`:
```json
{
"mcpServers": {
"yandex-webmaster": {
"command": "npx",
"args": ["-y", "yandex-webmaster-mcp-server"],
"env": {
"YANDEX_WEBMASTER_OAUTH_TOKEN": "your-token",
"YANDEX_WEBMASTER_HOST_URL": "https://example.com"
}
}
}
}
```
Or if installed from sources:
```json
{
"mcpServers": {
"yandex-webmaster": {
"command": "node",
"args": ["path/to/dist/index.js"],
"env": {
"YANDEX_WEBMASTER_OAUTH_TOKEN": "your-token",
"YANDEX_WEBMASTER_HOST_URL": "https://example.com"
}
}
}
}
```
## Available Tools
### Core --- basic operations (10)
Account management, hosts (sites), verification, and diagnostics.
| Tool | Description | Type |
|---|---|---|
| `ywm_get_user` | Get current user information | Read |
| `ywm_list_hosts` | List all registered hosts | Read |
| `ywm_get_host` | Get host details by ID | Read |
| `ywm_add_host` | Add a new host | Write |
| `ywm_delete_host` | Delete a host | Write |
| `ywm_get_host_summary` | Host summary (SQI, pages, issues) | Read |
| `ywm_get_verification` | Host verification status | Read |
| `ywm_verify_host` | Initiate host verification | Write |
| `ywm_get_diagnostics` | Site diagnostics and issues | Read |
| `ywm_list_owners` | List of host owners | Read |
### Content --- content and indexing (16)
Sitemaps, indexing status, URLs in search, important URLs, broken links, and search events.
| Tool | Description | Type |
|---|---|---|
| `ywm_list_sitemaps` | List all sitemaps | Read |
| `ywm_get_sitemap` | Get sitemap details | Read |
| `ywm_add_sitemap` | Add a sitemap | Write |
| `ywm_delete_sitemap` | Delete a sitemap | Write |
| `ywm_list_user_sitemaps` | List user sitemaps | Read |
| `ywm_get_user_sitemap` | Get user sitemap details | Read |
| `ywm_get_indexing_history` | Indexing history for a period | Read |
| `ywm_get_indexing_samples` | Indexing samples with HTTP codes | Read |
| `ywm_get_search_urls` | URLs found in search | Read |
| `ywm_get_search_urls_history` | Search URLs history for a period | Read |
| `ywm_get_important_urls` | Important URLs with issues | Read |
| `ywm_get_important_urls_history` | Important URLs history for a period | Read |
| `ywm_get_broken_internal_links` | Broken internal links examples | Read |
| `ywm_get_broken_links_history` | Broken links history for a period | Read |
| `ywm_get_search_events_samples` | Pages excluded from search (LOW_QUALITY, DUPLICATE, etc.) | Read |
| `ywm_get_search_events_history` | Search events history for a period | Read |
### Analytics --- analytics (7)
Search queries, external links, SQI, and advanced query analytics.
| Tool | Description | Type |
|---|---|---|
| `ywm_get_search_queries` | Search queries history | Read |
| `ywm_get_popular_queries` | Popular search queries | Read |
| `ywm_get_query_history` | Specific search query history | Read |
| `ywm_query_analytics` | Advanced query analytics with filters | Read |
| `ywm_get_external_links` | External links examples | Read |
| `ywm_get_external_links_history` | External links history for a period | Read |
| `ywm_get_sqi_history` | SQI history for a period | Read |
### Actions --- actions (13)
Page recrawling, original texts, and feed management.
| Tool | Description | Type |
|---|---|---|
| `ywm_get_recrawl_quota` | Recrawl quota | Read |
| `ywm_list_recrawl_tasks` | List of recrawl tasks | Read |
| `ywm_get_recrawl_task` | Recrawl task details | Read |
| `ywm_submit_recrawl` | Submit URL for recrawl (consumes quota) | Write |
| `ywm_get_original_texts` | Original texts list | Read |
| `ywm_add_original_text` | Add original text | Write |
| `ywm_delete_original_text` | Delete original text | Write |
| `ywm_get_original_text_quota` | Original texts quota | Read |
| `ywm_list_feeds` | List of all feeds | Read |
| `ywm_start_feed_upload` | Start feed upload | Write |
| `ywm_get_feed_upload_status` | Feed upload status | Read |
| `ywm_batch_add_feeds` | Mass add feeds | Write |
| `ywm_batch_remove_feeds` | Mass remove feeds | Write |
## Development
```bash
pnpm install # Install dependencies
pnpm dev # Run in development mode (watch)
pnpm build # Build for production
pnpm test # Run tests
pnpm test:watch # Run tests in watch mode
```
## License
MIT
