# 2gis Mcp

> MCP server for 2GIS — places, geocoding, directions, reviews (Russia). Part of WWmcp — 114 MCP servers for emerging markets.

- **Type:** MCP server
- **Install:** `agentstack add mcp-theyahia-2gis-mcp`
- **Verified:** Yes — security-reviewed for prompt injection and unsafe behavior
- **Seller:** [theYahia](https://agentstack.voostack.com/s/theyahia)
- **Installs:** 0
- **Category:** [AI & ML](https://agentstack.voostack.com/c/ai-and-ml)
- **Latest version:** 0.1.0
- **License:** MIT
- **Upstream author:** [theYahia](https://github.com/theYahia)
- **Source:** https://github.com/theYahia/2gis-mcp

## Install

```sh
agentstack add mcp-theyahia-2gis-mcp
```

Requires the [AgentStack CLI](https://agentstack.voostack.com/docs/cli). Works with Claude Code, Cursor, and any MCP-compatible agent.

## About

# @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

```json
{
  "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:

3. `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

```bash
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](https://github.com/theYahia)
- **Source:** [theYahia/2gis-mcp](https://github.com/theYahia/2gis-mcp)
- **License:** MIT

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

## Pricing

- **Free** — Free

## Security capabilities

Automated source analysis of v0.1.0 — what this tool can access:

- **Network access:** no
- **Filesystem access:** no
- **Shell / process execution:** no
- **Environment & secrets:** no
- **Dynamic code execution:** no

*"Yes" means the capability is present in the source — more access means more to trust, not that it is unsafe.*


## Versions

- **0.1.0** — security scan: passed — Imported from the upstream source.

## Links

- Listing page: https://agentstack.voostack.com/l/mcp-theyahia-2gis-mcp
- Seller: https://agentstack.voostack.com/s/theyahia
- Browse the marketplace: https://agentstack.voostack.com/browse

---
Listed on AgentStack — the marketplace for AI agent skills and MCP servers. Every listing is security-reviewed. Creators keep 70%.