ya-reviews-mcp

Model Context Protocol (MCP) server for Yandex Maps business reviews. Scrapes reviews from any Yandex Maps organization page and exposes them to your AI assistant — review text, ratings, author info, likes/dislikes, business responses, and company metadata.

No API key required. Uses a headless Chromium browser under the hood. Supports multiple browser backends: Playwright, Patchright (anti-detection), or a remote browser via CDP.

Quick Start

1. Install

Choose your backend:

# Option A: Playwright (default)
uv tool install ya-reviews-mcp[playwright]
playwright install chromium

# Option B: Patchright (better anti-detection)
uv tool install ya-reviews-mcp[patchright]
patchright install chromium

# Option C: Remote browser (no local browser needed)
uv tool install ya-reviews-mcp
# Then run a browser separately, e.g.:
# docker run -p 3000:3000 ghcr.io/browserless/chromium

No uv? Use pip instead: pip install ya-reviews-mcp[playwright]

2. Find the Organization ID

Open any business on Yandex Maps and look at the URL:

https://yandex.ru/maps/org/astra_motors/1248139252/reviews/
                                        ^^^^^^^^^^
                                        this is the org_id

3. Configure Your IDE

Add to your Claude Desktop / Cursor MCP configuration:

{
  "mcpServers": {
    "ya-reviews": {
      "command": "uvx",
      "args": ["--from", "ya-reviews-mcp[playwright]", "ya-reviews-mcp"]
    }
  }
}

Using Patchright? Replace ya-reviews-mcp[playwright] with ya-reviews-mcp[patchright] and add "--backend", "patchright" to args.

Running from source? Use uv run instead:

{
  "mcpServers": {
    "ya-reviews": {
      "command": "uv",
      "args": ["run", "--directory", "/path/to/ya-reviews-mcp", "ya-reviews-mcp"]
    }
  }
}

4. Start Using

Ask your AI assistant to:

• "Get reviews for organization 1248139252" — fetch all reviews with text, ratings, and business responses

• "Show me company info for org 1248139252" — company name, rating, review count

• "Give me a summary of org 1248139252 with the last 10 reviews" — company info + recent reviews in one call

Tools

3 tools for Yandex Maps review data:

Review Data Fields

Each review includes:

Company Info Fields

Configuration

All configuration via environment variables (no API key needed):

Copy .env.example to .env and uncomment the values you want to change.

CLI

# stdio (default, for MCP clients)
ya-reviews-mcp

# HTTP transport
ya-reviews-mcp --transport streamable-http --port 8000

# With verbose logging
ya-reviews-mcp -vv

# Use Patchright backend
ya-reviews-mcp --backend patchright

# Use remote browser
ya-reviews-mcp --backend remote --browser-url ws://localhost:3000

# Load custom .env file
ya-reviews-mcp --env-file /path/to/.env

How It Works

Unlike ya-metrics-mcp which uses the official Yandex Metrika API, Yandex Maps has no public API for reviews. This server uses a headless browser to:

1. Navigate to the organization's reviews page on yandex.ru/maps

2. Parse review data from the server-rendered DOM (schema.org structured data)

3. Scroll to load additional reviews (50 per scroll, infinite pagination)

4. Click "Show organization response" buttons to reveal business replies

5. Extract all fields including likes/dislikes and direct review URLs

A single Chromium browser instance is shared across requests via FastMCP's lifespan context. Each scrape creates a fresh browser context (isolated cookies/state).

Development

# Install with dev dependencies (includes playwright)
uv sync --extra dev

# Install browser
uv run playwright install chromium

# Run tests
uv run pytest

# Lint
uv run ruff check src/

# Type check
uv run mypy src/

License

MIT