2gis Mcp

@theyahia/2gis-mcp

MCP server for the 2GIS API — places search, geocoding, directions, public transport, autocomplete and reviews, for AI agents. Coverage is Russia/CIS (and other 2GIS regions); responses are mostly in Russian.

Tools (9)

| Tool | Description | |------|-------------| | search_places | Search places/businesses with spatial filtering + pagination | | get_place | Detailed place info by 2GIS ID | | search_by_rubric | Search by category (rubric) ID near a point | | geocode | Address → coordinates | | reverse_geocode | Coordinates → address | | get_directions | Car/walking/bicycle/taxi/scooter route between two points | | get_public_transport | Public-transport route (metro/bus/tram/trolleybus) | | suggest | Address/place autocomplete | | get_reviews | Rating + review count (official) and review texts (best-effort) |

All tools are read-only and annotated as such (readOnlyHint, openWorldHint). A 2gis://rubrics resource explains how to obtain rubric IDs.

Setup

1. Get an API key at https://dev.2gis.com/ (a free demo key works for trying it out).
2. Set the environment variable TWOGIS_API_KEY.

Claude Desktop / Claude Code

{
  "mcpServers": {
    "2gis": {
      "command": "npx",
      "args": ["-y", "@theyahia/2gis-mcp"],
      "env": { "TWOGIS_API_KEY": "your-key" }
    }
  }
}

Optional env: TWOGIS_TIMEOUT_MS (request timeout, default 10000), TWOGIS_LOCALE (routing locale, default ru).

API key & scopes

2GIS issues a key per subscription, and that one key works for every service included in the subscription. So a single TWOGIS_API_KEY can cover Catalog (places/geocode/suggest), Routing (directions) and Public Transport — only if your subscription enables those services. Notes:

• A demo key is created once, valid ~1 month, ~1000 requests per service;

for Places it additionally caps page_size ≤ 10 and page ≤ 5.

• A key bound to an App ID is for the mobile SDK only and will fail for direct

HTTP API calls — create a separate key for this server.

• A 403 typically means the service isn't enabled for your key/subscription.

Typical workflow

get_place and get_reviews need a 2GIS ID. Get it from search_places:

1. search_places(query: "кофейня", point: "82.92,55.03") → take items[].id.
2. get_place(place_id: ) or get_reviews(place_id: ).

For search_by_rubric, take a rubric id from the rubrics: [{ id, name }] field of search_places results (or read the 2gis://rubrics resource), then:

1. search_by_rubric(rubric_id: , point: "82.92,55.03").

Coordinates — lon,lat order

point parameters use lon,lat (longitude first), e.g. "82.92,55.03" — not lat,lon. Inputs are validated for order/bounds. The *_lat / *_lon numeric parameters (directions, reverse_geocode, suggest) are unambiguous.

Pagination & limits

search_places / search_by_rubric accept page (1-based) and page_size (≤ 50). search_places radius ≤ 40000 m (with a query); search_by_rubric radius ≤ 2000 m (query-less). Demo keys cap page ≤ 5 / page_size ≤ 10.

Reviews

The Places API only exposes review statistics (rating + count) to self-service keys — get_reviews always returns those. Review texts are fetched from an undocumented internal endpoint on a best-effort basis; for many keys this returns nothing (you'll get the stats plus a note). Treat texts as unofficial.

Public transport

get_public_transport calls the 2GIS Public Transport API (a separate endpoint from car routing). It requires a subscription that includes that API; without it you may get a 403.

Troubleshooting

| Symptom | Likely cause | |---|---| | Authentication failed (401) | Wrong/empty TWOGIS_API_KEY | | Access forbidden (403) | Service not enabled for your subscription, or an SDK (App ID) key used for HTTP | | Rate limit exceeded (429) | Per-service quota hit; retried with backoff, then surfaced | | Request timed out | Network/2GIS latency; raise TWOGIS_TIMEOUT_MS | | Empty no_results | No matches, or coordinates given as lat,lon instead of lon,lat |

Demo prompts

• "Find coffee shops near Новосибирск центр in 2GIS"
• "What is at coordinates 55.0302, 82.9204?"
• "Get walking directions from 55.0302,82.9204 to 54.8430,83.0972"
• "Public transport from Площадь Ленина to Академгородок"
• "Suggest addresses starting with 'Москва, Твер'"
• "Find pharmacies near me by rubric"
• "Rating and reviews for place 141265770013120"

Development

npm install
npm run typecheck   # tsc --noEmit
npm run lint        # biome check
npm run build       # tsc → dist/
npm test            # vitest (unit + stdio smoke)
npm run inspector   # @modelcontextprotocol/inspector against the built server

Tests are unit-level (mocked fetch) plus an stdio handshake smoke test — no live API calls. To verify against the real API, set TWOGIS_API_KEY and exercise the tools via npm run inspector.

License

MIT — see [LICENSE](LICENSE).

Source & license

This open-source MCP server is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: theYahia
• Source: theYahia/2gis-mcp
• License: MIT

Install and usage instructions live in the source repository linked above.