claude-yandex-tools

claude-yandex-tools

An MCP server that gives Claude (or any MCP client) access to Yandex geo and transport APIs: geocoding, place search, traffic-aware routing and public transport timetables.

Built for people in Russia and the CIS, where Google Maps coverage is thin and Yandex is what actually works.

Single static Go binary, no runtime dependencies.

Tools

Only tools whose API key is configured get registered. Set one key and you get one tool; the model never sees a tool it cannot call.

What this does not do

No Yandex Market product search, and no Yandex Eda ordering. This is deliberate, not a missing feature:

• Yandex Market's public content API was discontinued. The remaining Partner API only exposes your own listings as a seller. Product search would mean scraping — against the terms of service, blocked by anti-bot measures, and broken by the next markup change.
• Yandex Eda has no consumer API. Ordering food would mean emulating the mobile app, and handing an LLM an agent-callable tool that spends real money from a saved card is a bad idea regardless of whether it is technically possible.

Issues asking for either will be closed. Everything here runs on documented, official APIs.

Install

go install github.com/devnulll-org/claude-yandex-tools@latest

Or build from source:

git clone https://github.com/devnulll-org/claude-yandex-tools
cd claude-yandex-tools
go build -o claude-yandex-tools .

Getting API keys

Each service issues its own key in the Yandex developer dashboard. A Geocoder key will not work for Places — this trips up everyone once.

Key activation takes up to 15 minutes. Until then every call returns HTTP 403.

Configure your MCP client

Claude Code:

claude mcp add yandex \
  -e YANDEX_GEOCODER_API_KEY=your_key \
  -e YANDEX_GEOSEARCH_API_KEY=your_key \
  -e YANDEX_ROUTING_API_KEY=your_key \
  -- /path/to/claude-yandex-tools

Claude Desktop (claude_desktop_config.json):

{
  "mcpServers": {
    "yandex": {
      "command": "/path/to/claude-yandex-tools",
      "env": {
        "YANDEX_GEOCODER_API_KEY": "your_key",
        "YANDEX_GEOSEARCH_API_KEY": "your_key",
        "YANDEX_ROUTING_API_KEY": "your_key"
      }
    }
  }
}

Then ask things like:

Find three coffee shops near Патриаршие пруды that are open now, and tell me which is fastest to reach by car from Курский вокзал.

Quotas, throttling and caching

Yandex free-tier keys are tight — the HTTP Geocoder allows about 1000 requests a day — and Yandex blocks keys for overrun rather than returning a soft error. A blocked key takes a support ticket to restore. An agent issuing parallel tool calls can burn through that budget fast, so the server defends the key:

• Daily budget per service, persisted to disk so a restart does not hand back spent quota. Defaults are conservative; override with YANDEX_GEOCODER_DAILY_LIMIT, YANDEX_GEOSEARCH_DAILY_LIMIT, YANDEX_ROUTING_DAILY_LIMIT, YANDEX_RASP_DAILY_LIMIT.
• Throttling to at least 120 ms between calls to one service, so parallel tool calls do not look like a burst.
• Caching of geocoder results for 30 days and timetables for 6 hours. Addresses do not move, and repeated geocoding of the same place is the single biggest quota waster.

Cache location defaults to $XDG_CACHE_HOME/claude-yandex-tools/cache.json; override with YANDEX_MCP_CACHE.

Routing and Places results are never cached. Routes are traffic-dependent, and the Places API is offered under a licence that forbids storing its data. That constraint is pinned by a test so it cannot be "optimised" away.

Licensing and terms — read this

This project is a client library. It ships no API keys and grants no rights to Yandex data. You use your own key under your own agreement with Yandex, and you are responsible for staying inside your tariff's terms.

One clause deserves attention: on some Yandex Maps tariffs, free use requires that results be displayed on a Yandex map. An MCP server returns data into a chat, which may not satisfy that condition. Check the terms of the tariff you sign up for, especially before using this commercially.

Development

go test ./...
go build -o claude-yandex-tools .

Tests use stub HTTP servers and never call the real API, so they run without keys.

Licence

MIT — see LICENSE.

Not affiliated with or endorsed by Yandex or Anthropic.