MCP-сервер

MCP-сервер 2ГИС предоставляет ИИ-агентам доступ к геоданным 2ГИС: картам, адресам, маршрутам и данным об организациях. Он использует открытый протокол Model Context Protocol, направляет запросы от ИИ-агентов к API 2ГИС и возвращает результаты в подходящем для обработки формате. ИИ-ассистенты используют эти данные, чтобы отвечать на вопросы пользователей о местах, адресах, организациях и маршрутах, а также анализировать и визуализировать данные.

Схема работы:

Пользователь отправляет запрос ИИ-агенту (например, Найти все круглосуточные аптеки).
Агент определяет, какие геоданные и сервисы нужны (карты, поиск объектов по критерию и т. д.), и обращается к MCP-серверу.
MCP-сервер отправляет запросы к соответствующим API 2ГИС (например, Static API для получения изображения карты, Places API для поиска объектов и получения данных о них).
Агент получает результат и формирует ответ для пользователя.

При использовании MCP-сервера и при прямом обращении к API доступны одни и те же данные и действуют одинаковые тарифы и лимиты.

Доступные инструменты и API

MCP-сервер предоставляет следующие инструменты для работы:

Инструмент	Функция	Используемое API 2ГИС
`search_poi`	Поиск мест и организаций по запросу и координатам	Places API, Geocoder API
`calculate_route`	Построение маршрутов на разных видах транспорта, расчёт времени в пути и расстояния.	Routing API
`geocode`	Прямое геокодирование: преобразование адреса в координаты	Geocoder API
`reverse_geocode`	Обратное геокодирование: преобразование координат в адрес	Geocoder API
`create_map_view`	Создание статической карты с маркерами в формате PNG	Static API
`calculate_isochrone`	Построение областей, которые достижимы от начальной точки за определённое время (изохрон).	Isochrone API

1. Получите ключ доступа

Зарегистрируйтесь в личном кабинете Менеджер Платформы.
Получите ключ для доступа к нужным API:
- Оформите бесплатный демо-ключ (действует 30 дней, есть ограничения по количеству запросов). В демо-ключе автоматически подключены все нужные API для работы с MCP-сервером.
- Купите подписку и создайте ключи для доступа к API. Рекомендуется создать два ключа для работы с MCP-сервером, чтобы отдельно контролировать использование API карт и поиска и API навигации. Количество ключей не влияет на стоимость подписки. Рекомендуемое распределение API по ключам:
  - Ключ для работы с картами и поиском: Static API, Geocoder API, Places API.
  - Ключ для работы с навигацией: Routing API, Isochrone API.
Если вы создаёте только один ключ, убедитесь, что в нём подключены все нужные API для работы с MCP-сервером. Подробнее о работе с ключами и подписками см. в документации личного кабинета.

Подробнее о стоимости сервисов см. в разделе Тарифы.

2. Установите и настройте MCP-сервер

Клонируйте репозиторий MCP-сервера.
Установите зависимости:
```
npm install
```
Запустите сборку MCP-сервера:
```
npm run build
```
После сборки в корне репозитория будет создан файл dist/index.js, путь до которого нужно указать в конфигурации запуска на следующем шаге.

3. Подключите MCP-сервер к приложению

Claude Desktop
LM Studio
Cursor
VS Code (GitHub Copilot)
Любой MCP-совместимый клиент

Скачайте и установите Claude Desktop.
В файл настроек claude_desktop_config.json добавьте конфигурацию MCP-сервера 2ГИС:
```
{
  "mcpServers": {
    "2gis": {
      "command": "node",
      "args": ["PATH_TO_REPO/dist/index.js"],
      "env": {
        "MAPGL_API_KEY": "YOUR_MAPS_API_KEY",
        "ROUTING_API_KEY": "YOUR_ROUTING_API_KEY"
      }
    }
  }
}
```
Где:
- PATH_TO_REPO — путь к папке с репозиторием MCP-сервера, в которой находится файл dist/index.js.
- YOUR_MAPS_API_KEY — ваш API-ключ для работы с картами и поиском.
- YOUR_ROUTING_API_KEY — ваш API-ключ для работы с навигацией. Если вы используете один ключ для всех API, укажите его в обеих переменных.
Если сервер развёрнут удалённо (с доступом по HTTP), используйте Supergateway:
```
{
  "mcpServers": {
    "2gis": {
      "command": "npx",
      "args": [
        "-y",
        "supergateway",
        "--streamableHttp",
        "https://YOUR_HOST/mcp"
      ]
    }
  }
}
```

LM Studio позволяет работать с MCP-сервером полностью локально: без облачных LLM-провайдеров. Модель работает на вашем компьютере, а MCP-сервер обращается только к API 2ГИС.

Скачайте и установите LM Studio.
Подключите MCP-сервер по инструкции. В файл настроек mcp.json добавьте конфигурацию MCP-сервера 2ГИС:
```
{
  "mcpServers": {
    "2gis": {
      "command": "node",
      "args": ["PATH_TO_REPO/dist/index.js"],
      "env": {
        "MAPGL_API_KEY": "YOUR_MAPS_API_KEY",
        "ROUTING_API_KEY": "YOUR_ROUTING_API_KEY"
      }
    }
  }
}
```
Где:
- PATH_TO_REPO — путь к папке с репозиторием MCP-сервера, в которой находится собранный файл dist/index.js.
- YOUR_MAPS_API_KEY — ваш API-ключ для работы с картами и поиском.
- YOUR_ROUTING_API_KEY — ваш API-ключ для работы с навигацией. Если вы используете один ключ для всех API, укажите его в обеих переменных.

Скачайте и установите Cursor.
В файл настроек .cursor/mcp.json добавьте конфигурацию MCP-сервера 2ГИС:
```
{
  "mcpServers": {
    "2gis": {
      "command": "node",
      "args": ["PATH_TO_REPO/dist/index.js"],
      "env": {
        "MAPGL_API_KEY": "YOUR_MAPS_API_KEY",
        "ROUTING_API_KEY": "YOUR_ROUTING_API_KEY"
      }
    }
  }
}
```
Где:
- PATH_TO_REPO — путь к папке с репозиторием MCP-сервера, в которой находится собранный файл dist/index.js.
- YOUR_MAPS_API_KEY — ваш API-ключ для работы с картами и поиском.
- YOUR_ROUTING_API_KEY — ваш API-ключ для работы с навигацией. Если вы используете один ключ для всех API, укажите его в обеих переменных.

Скачайте и установите VS Code.
Создайте файл .vscode/mcp.json в корне рабочей директории и добавьте конфигурацию MCP-сервера 2ГИС:
```
{
  "servers": {
    "2gis": {
      "command": "node",
      "args": ["PATH_TO_REPO/dist/index.js"],
      "env": {
        "MAPGL_API_KEY": "YOUR_MAPS_API_KEY",
        "ROUTING_API_KEY": "YOUR_ROUTING_API_KEY"
      }
    }
  }
}
```
Где:
- PATH_TO_REPO — путь к папке с репозиторием MCP-сервера, в которой находится собранный файл dist/index.js.
- YOUR_MAPS_API_KEY — ваш API-ключ для работы с картами и поиском.
- YOUR_ROUTING_API_KEY — ваш API-ключ для работы с навигацией. Если вы используете один ключ для всех API, укажите его в обеих переменных.

MCP-сервер 2ГИС работает по стандартному MCP-протоколу через stdio. Любое приложение, поддерживающее протокол MCP, может подключиться к серверу, указав команду запуска:

MAPGL_API_KEY=YOUR_MAPS_API_KEY ROUTING_API_KEY=YOUR_ROUTING_API_KEY node dist/index.js

Где:

YOUR_MAPS_API_KEY — ваш API-ключ для работы с картами и поиском.
YOUR_ROUTING_API_KEY — ваш API-ключ для работы с навигацией. Если вы используете один ключ для всех API, укажите его в обеих переменных.

Пример работы

Изображения ниже показывают примеры использования MCP-сервера 2ГИС в диалоге пользователя с ИИ-ассистентом:

Поиск объектов по критериям:
Отображение объекта на карте:
Расчёт маршрута:

Доступные инструменты и API​

1. Получите ключ доступа​

2. Установите и настройте MCP-сервер​

3. Подключите MCP-сервер к приложению​

Пример работы​

Доступные инструменты и API

1. Получите ключ доступа

2. Установите и настройте MCP-сервер

3. Подключите MCP-сервер к приложению

Пример работы