Локальный MCP-сервер

Скачиваемый дистрибутив MCP-сервера позволяет развернуть сервер локально и использовать его с ИИ-агентами.

Требования

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

• Ключ доступа к API 2ГИС.
• ИИ-клиент с поддержкой протокола MCP для взаимодействия с локальным сервером.

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

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

Инструмент	Функция	Сервис
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. Получите ключ доступа

1. Зарегистрируйтесь в личном кабинете Менеджер Платформы.

2. Получите ключ для доступа к нужным API:

   • Оформите бесплатный демо-ключ (действует 30 дней, есть ограничения по количеству запросов). В демо-ключе автоматически подключены все нужные API для работы с MCP-сервером.

   • Купите подписку и создайте ключи для доступа к API. Рекомендуется создать два ключа для работы с MCP-сервером, чтобы отдельно контролировать использование API карт и поиска и API навигации. Количество ключей не влияет на стоимость подписки. Рекомендуемое распределение API по ключам:

     • Ключ для работы с картами и поиском: Static API, Geocoder API, Places API.
     • Ключ для работы с навигацией: Routing API, Isochrone API.

   Если вы создаёте только один ключ, убедитесь, что в нём подключены все нужные API для работы с MCP-сервером. Подробнее о работе с ключами и подписками см. в документации личного кабинета.

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

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

1. Клонируйте репозиторий MCP-сервера.

2. Установите зависимости:

   npm install

3. Запустите сборку MCP-сервера:

   npm run build

   После сборки в корне репозитория будет создан файл dist/index.js, путь до которого нужно указать в конфигурации запуска на следующем шаге.

3. Подключите 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

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

Подключите 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 (GitHub Copilot)

Создайте файл .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-совместимый клиент

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, укажите его в обеих переменных.