Mapbox

Mapbox MCP Server

Сервер Node.js, реализующий Model Context Protocol (MCP) для API Mapbox.

Откройте геопространственные возможности для своих приложений с ИИ

Mapbox MCP Server превращает любого ИИ-агента или приложение в систему, учитывающую геопространственный контекст, обеспечивая беспрепятственный доступ к комплексной платформе Mapbox для работы с геоданными. С помощью этого сервера ваш ИИ сможет понимать места и рассуждать о них, ориентироваться в физическом мире и получать доступ к обширным геопространственным данным, включая:

• Глобальное геокодирование для преобразования адресов и названий мест в координаты и обратно
• Поиск точек интереса (POI) среди миллионов компаний, достопримечательностей и мест по всему миру
• Маршрутизация с учетом разных способов передвижения на автомобиле, пешком и на велосипеде с учетом дорожной обстановки в реальном времени
• Матрицы времени в пути для анализа доступности и оптимизации логистики
• Оптимизация маршрутов для определения оптимального порядка посещения нескольких остановок (задача коммивояжера)
• Привязка к дорожной сети для привязки GPS-треков к дорожной сети и наглядного отображения маршрутов
• Построение изохрон для визуализации областей, доступных в пределах заданного времени или расстояния
• Интерактивное отображение карт в реальном времени (render_map_tool) для показа маршрутов, результатов поиска и ваших собственных GeoJSON непосредственно в чате на настоящей карте Mapbox GL JS
• Статические изображения карт для создания наглядных представлений мест, маршрутов и географических данных
• Автономные геопространственные вычисления расстояний, площадей, азимутов, буферных зон и пространственный анализ без обращения к API

Создаете ли вы ИИ-помощника для путешествий, оптимизатор логистики, рекомендательную систему на основе местоположения или любое другое приложение, которому нужно понимать, «где» что находится, Mapbox MCP Server предоставляет необходимые пространственные возможности. Его также можно подключить к популярным клиентам, например Claude Desktop и VS Code. Подробности приведены ниже.

Использование

Для работы с этим MCP-сервером необходим токен доступа Mapbox.

Размещенная конечная точка MCP

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

Конечная точка: https://mcp.mapbox.com/mcp

Подробные инструкции по настройке различных клиентов и использованию API см. в руководстве по размещенному MCP Server.

Чтобы получить токен доступа Mapbox:

1. Зарегистрируйте бесплатную учетную запись Mapbox на mapbox.com/signup
2. Перейдите на свою страницу учетной записи
3. Создайте новый токен или используйте токен по умолчанию для публичного доступа

Дополнительные сведения о токенах доступа Mapbox см. в документации Mapbox о токенах доступа.

Руководства по интеграции

Подробные инструкции по настройке различных интеграций см. в следующих руководствах:

• Настройка Claude Desktop — инструкции по настройке Claude Desktop для работы с этим MCP-сервером
• Настройка Goose — настройка фреймворка ИИ-агентов Goose
• Настройка VS Code — настройка среды разработки в Visual Studio Code
• Настройка Cursor AI IDE — настройка среды разработки в Cursor AI IDE
• Интеграция Smolagents — пример подключения ИИ-агентов Smolagents к инструментам Mapbox
• Прямой импорт инструментов — используйте инструменты Mapbox в собственных приложениях без запуска MCP-сервера
• Руководство по render_map_tool — примитив визуализации карт: полная схема полезной нагрузки и инструкции по самостоятельному отображению собственных данных без использования других инструментов Mapbox
• Запросы уточнения — как search_and_geocode_tool и directions_tool предлагают пользователю уточнить неоднозначные результаты или выбрать маршрут, а также как они корректно работают, если клиент не поддерживает эту возможность

Примеры запросов

После настройки попробуйте эти запросы в Claude Desktop или других MCP-клиентах:

Определение местоположения

Для запросов, в которых исходными данными служат координаты, например «что находится рядом со мной», «что это за район», «куда можно добраться за N минут», используйте ground_location_tool. Этот инструмент объединяет обратное геокодирование, поиск по категориям и построение изохрон в одном вызове, адаптивно выбирая подходящую стратегию в зависимости от запроса. Он возвращает типизированные записи (названия, адреса, координаты, расстояния, полигоны доступности) с указанием источников.

Каждый из четырех запросов ниже проверяет отдельную стратегию в рамках одного вызова инструмента:

• Район — «Что за район находится по координатам 47.6097, -122.3408 и что есть поблизости?»
• POI — «Кофейни в пределах 10 минут ходьбы от 40.7580, -73.9855»
• Область — «Куда можно дойти пешком за 15 минут от 37.7749, -122.4194?»
• Маршрутизация — «Ближайшая точка на маршруте, где можно высадить пассажира, рядом с 34.0522, -118.2437»

Поиск мест

• «Найди кофейни в пешей доступности от Эмпайр-стейт-билдинг»
• «Я хочу поехать из Сиэтла в Портленд. Есть ли по пути Starbucks?»
• «Покажи заправки вдоль маршрута из Бостона в Нью-Йорк»
• «Какие рестораны есть рядом с Таймс-сквер?»

Навигация и поездки

• «Построй автомобильный маршрут из LAX в Голливуд с учетом текущей дорожной обстановки»
• «Сколько времени займет пешая прогулка от Центрального парка до Таймс-сквер?»
• «Рассчитай время поездки на такси от моего отеля (Four Seasons) до аэропорта JFK в час пик»

Визуализация и карты

• «С помощью инструмента отображения карт Mapbox покажи маршрут от моста Золотые Ворота до Юнион-сквер в Сан-Франциско» — отображает интерактивный маршрут в реальном времени на настоящей карте Mapbox
• «Создай изображение карты с маршрутом от моста Золотые Ворота до Рыбацкой пристани и маркерами в обоих местах»
• «Покажи спутниковый снимок Манхэттена с отмеченными основными достопримечательностями»
• «Создай карту, на которой отмечены все магазины Starbucks в радиусе мили от центра Сиэтла»
• «Покажи полигон-заливку по этим координатам: [...], а также маркер с подписью „Склад“ в точке [...]» — отображает ваш GeoJSON напрямую через render_map_tool, без использования других инструментов Mapbox

Анализ и планирование

• «Покажи области, до которых можно добраться на автомобиле за 30 минут из центра Портленда»
• «Рассчитай матрицу времени в пути между этими тремя отелями (Marriott, Sheraton и Hilton) и конференц-центром в Денвере»
• «Найди оптимальный маршрут для посещения этих трех туристических достопримечательностей в Сан-Франциско: моста Золотые Ворота, Музыкальной лестницы и Рыбацкой пристани»
• «Оптимизируй маршрут доставки по этим восьми адресам: [список адресов]»

GPS и привязка маршрутов

• «Очисти этот GPS-трек и покажи фактический маршрут по дорогам: [список координат с временными метками]»
• «Привяжи этот записанный маршрут велосипедной поездки к велосипедной сети: [координаты GPS]»
• «Привяжи этот автомобильный маршрут к дорожной сети и покажи уровень загруженности дорог»

Автономные геопространственные вычисления

• «Каково расстояние в милях между этими двумя координатами?»
• «Рассчитай площадь этого полигона в квадратных километрах»
• «Находится ли точка 37.7749°N, 122.4194°W внутри этого полигона зоны обслуживания?»
• «Каков азимут из Сан-Франциско в Нью-Йорк?»
• «Найди середину между Лондоном и Парижем»
• «Создай буферную зону радиусом 5 миль вокруг этого места»
• «Рассчитай центроид границы этого района»
• «Какова ограничивающая рамка для этих координат маршрута?»
• «Упрости этот сложный полигон, чтобы уменьшить количество точек»

Советы для получения лучших результатов

• Указывайте точные места (используйте полные адреса или названия достопримечательностей)
• Указывайте предпочтительный способ передвижения (автомобиль, пешком, велосипед)
• При необходимости задавайте временные ограничения («в час пик», «в 15:00»)
• При необходимости указывайте желаемый формат результата («в виде изображения карты», «в формате JSON»)

Подробные примеры: см. examples/search-along-route.md, где приведены подробные примеры запросов для поиска вдоль маршрута в разных сценариях и инструкции по тестированию с помощью MCP Inspector.

Ресурсы

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

Доступные ресурсы

Ресурс категорий Mapbox

Шаблон URI: mapbox://categories или mapbox://categories/{language}

Получите полный список доступных идентификаторов категорий для использования с инструментом поиска по категориям. Категории можно использовать для фильтрации результатов поиска по типу (например, «ресторан», «отель», «заправка»).

Примеры:

• mapbox://categories — список категорий по умолчанию (на английском языке)
• mapbox://categories/ja — названия категорий на японском языке
• mapbox://categories/es — названия категорий на испанском языке

Доступ к ресурсам:

• Клиенты со встроенной поддержкой ресурсов MCP: используйте метод протокола MCP resources/read
• Клиенты без поддержки ресурсов: используйте resource_reader_tool с URI ресурса

Расширенные предпросмотры карт (render_map_tool)

Каждый геопространственный инструмент этого сервера (маршруты, изохроны, поиск и другие) может отображать результат на интерактивной карте Mapbox GL JS в реальном времени с помощью render_map_tool — единственного примитива визуализации сервера. Он отображает карту в виде автономной HTML-панели непосредственно в чате через протокол MCP Apps (@modelcontextprotocol/ext-apps), с кнопкой полноэкранного режима, в следующих поддерживаемых клиентах:

• Claude Desktop ✅
• VS Code с GitHub Copilot ✅
• Claude Code ✅
• Goose ✅

Для этого не нужны никакие другие инструменты сервера. render_map_tool также принимает GeoJSON, составленный вручную: ваши собственные полигоны, маркеры и маршруты — без зависимости от directions_tool, isochrone_tool или любых других вызовов API Mapbox. Схему полезной нагрузки и полный автономный пример см. в полном руководстве по render_map_tool.

Если вам нужно гарантированное статическое изображение в клиентах без поддержки MCP Apps, используйте вместо этого static_map_image_tool — он возвращает изображение PNG/JPEG в кодировке base64, которое могут отображать все клиенты.

CLIENT_NEEDS_RESOURCE_FALLBACK

Инструменты резервного доступа к ресурсам (включаются для клиентов, не соответствующих требованиям)

Ресурсы — это основная функция MCP, поддерживаемая большинством клиентов (Claude Desktop, VS Code, MCP Inspector и другими). Однако некоторые клиенты (например, smolagents) вообще не поддерживают ресурсы. Для таких клиентов сервер может предоставлять «инструменты резервного доступа к ресурсам», которые передают то же содержимое, что и ресурсы, но через вызовы инструментов.

Резервные инструменты:

• resource_reader_tool — универсальный инструмент для чтения любого ресурса по URI
• category_list_tool — предоставляет доступ к списку категорий (mapbox://categories)

По умолчанию эти инструменты НЕ включены (предполагается, что клиент поддерживает ресурсы). Если клиент не поддерживает ресурсы, включите резервные инструменты:

export CLIENT_NEEDS_RESOURCE_FALLBACK=true

Когда следует включить эту настройку:

• ✅ Установите значение true, если используете smolagents или другие клиенты без поддержки ресурсов
• ❌ Не задавайте значение (по умолчанию), если используете Claude Desktop, VS Code, MCP Inspector или любой клиент с поддержкой ресурсов
• ❌ Если не уверены, не задавайте значение (большинство клиентов поддерживают ресурсы)

Инструменты

Вспомогательные инструменты

Инструмент чтения ресурсов

Предоставляет доступ к ресурсам MCP для клиентов, не поддерживающих встроенный API ресурсов MCP. Используйте этот инструмент для чтения ресурсов, например списка категорий.

Параметры:

• uri: URI ресурса для чтения (например, mapbox://categories, mapbox://categories/ja)

Примеры использования:

• Прочитать категории по умолчанию: {"uri": "mapbox://categories"}
• Прочитать категории на японском языке: {"uri": "mapbox://categories/ja"}

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

Автономные геопространственные инструменты

Эти инструменты выполняют геопространственные вычисления полностью автономно, без вызовов API Mapbox. Для точных географических вычислений они используют Turf.js и работают в любом месте, даже без подключения к интернету.

Инструмент расчета расстояния

Рассчитывает расстояние между двумя географическими координатами по формуле гаверсинусов.

Возможности:

• Поддерживает несколько единиц измерения: километры, мили, метры, футы, морские мили
• Точный расчет расстояния по дуге большого круга
• Не требует вызовов API

Пример использования: «Каково расстояние между Сан-Франциско (37.7749°N, 122.4194°W) и Нью-Йорком (40.7128°N, 74.0060°W)?»

Инструмент проверки точек внутри полигона

Проверяет одну или несколько точек на принадлежность полигону или мультиполигону и возвращает только точки внутри него. Поддерживает проверку одной точки или пакета точек за один вызов.

Возможности:

• Работает со сложными полигонами, включая полигоны с отверстиями
• Поддерживает мультиполигоны
• Проверяет любое количество точек за один вызов
• Полезен для геозонирования, проверки зон доставки и сегментации клиентов

Пример использования: «Какие из этих адресов доставки находятся в нашей зоне обслуживания?»

Инструмент Destination

Вычисляет точку назначения по начальной точке, азимуту и расстоянию, используя геодезическое смещение (по дуге большого круга).

Возможности:

• Смещение по прямой, а не по маршруту
• Полезен для запросов вроде «найди точку в 5 км к северу от X» или для создания смещений при поиске
• Не требует вызовов API

Пример использования: «Где находится точка в 10 км к северо-востоку от Space Needle?»

Инструмент Bearing

Вычисляет направление по компасу (азимут) от одной координаты до другой.

Возможности:

• Возвращает азимут в градусах (0–360°)
• Указывает направление по сторонам света (N, NE, E, SE, S, SW, W, NW)
• Полезен для навигации и запросов о направлении

Пример использования: «В каком направлении мне идти отсюда до аэропорта?»

Инструмент Midpoint

Находит географическую середину между двумя координатами вдоль дуги большого круга.

Возможности:

• Вычисляет истинную середину на искривлённой поверхности Земли
• Полезен для предложений места встречи
• Корректно обрабатывает вычисления для больших расстояний

Пример использования: «Где находится середина пути между Сан-Франциско и Нью-Йорком?»

Инструмент Centroid

Вычисляет геометрический центр (центроид) полигона или мультиполигона.

Возможности:

• Работает со сложными фигурами
• Возвращает среднее арифметическое всех точек
• Полезен для размещения подписей или маркеров

Пример использования: «Где разместить маркер для этой границы района?»

Инструмент Area

Вычисляет площадь полигона.

Возможности:

• Поддерживает несколько единиц измерения: квадратные метры, квадратные километры, акры, гектары, квадратные мили, квадратные футы
• Точно вычисляет площадь на поверхности Земли
• Работает с полигонами любого размера

Пример использования: «Какова площадь этого парка в акрах?»

Инструмент Bounding Box

Вычисляет минимальную ограничивающую рамку (bbox), содержащую геометрию.

Возможности:

• Работает с точками, линиями, полигонами и мультиполигонами
• Возвращает [minLongitude, minLatitude, maxLongitude, maxLatitude]
• Полезен для вычисления области просмотра и пространственной индексации

Пример использования: «Какова ограничивающая рамка этого маршрута?»

Инструмент Buffer

Создаёт буферную зону (полигон) вокруг точки, линии или полигона.

Возможности:

• Поддерживает несколько единиц измерения расстояния
• Создаёт круглые буферы вокруг точек
• Полезен для анализа близости и создания зон влияния

Пример использования: «Покажи буферную зону радиусом 5 км вокруг этого места»

Инструмент Simplify

Уменьшает количество вершин линии или полигона с помощью алгоритма Дугласа — Пекера.

Возможности:

• Настраиваемый допуск для уровня детализации
• Сохраняет общую форму, уменьшая сложность
• Полезен для уменьшения размера файлов и повышения производительности отрисовки
• Возможность сохранять топологию (предотвращать самопересечения)

Пример использования: «Упрости эту сложную границу, чтобы уменьшить количество точек»

Инструмент Length

Измеряет общую длину линии, заданной последовательностью координат.

Возможности:

• Поддерживает километры, мили, метры и футы
• Полезен для измерения нарисованного маршрута, пути или границы без вызова API маршрутизации

Пример использования: «Какова длина этой туристической тропы?»

Инструмент Convex

Вычисляет выпуклую оболочку набора точек — наименьший выпуклый полигон, содержащий их все.

Возможности:

• Полезен для анализа ограничивающей области или оценки площади покрытия
• Работает офлайн, без вызовов API

Пример использования: «Какой наименьший полигон содержит все эти магазины?»

Инструмент Nearest Point

Находит ближайшую точку в наборе к заданной целевой точке.

Возможности:

• Эффективнее, чем вызывать distance_tool для каждого кандидата и сортировать результаты
• Полезен для поиска ближайшего магазина, остановки или достопримечательности

Пример использования: «Какой из этих магазинов ближе всего к моему текущему местоположению?»

Инструмент Nearest Point on Line

Привязывает точку к ближайшему месту на линии или маршруте и возвращает эту точку и расстояние до неё.

Возможности:

• Полезен для запросов вроде «какая точка на этом маршруте ближе всего к моему местоположению?» или для привязки к карте без вызова API

Пример использования: «В какой точке этой туристической тропы я сейчас нахожусь ближе всего?»

Инструменты Union, Intersect и Difference

Объединяют или сравнивают два или более полигонов: union_tool объединяет их в одну геометрию, intersect_tool находит общую для них область, а difference_tool вычитает один полигон из другого.

Возможности:

• Полезны для объединения зон обслуживания, поиска пересечений областей покрытия или вычисления зон исключения (например, «что покрывает зона A, но не зона B?»)
• Работают полностью офлайн — вызовы API не требуются
• Каждый инструмент возвращает ссылку render_map_tool, чтобы результат можно было сразу визуализировать

Пример использования: «Объедини эти две зоны доставки в одну область покрытия» / «Где пересекаются эти две изохроны?» / «Какая часть этой зоны обслуживания не покрывается нашей 15-минутной изохроной?»

Инструменты API Mapbox

Инструмент Category List (устарел)

⚠️ Устарел: Вместо него используйте resource_reader_tool с URI mapbox://categories или напрямую обратитесь к ресурсу mapbox://categories, если ваш клиент поддерживает ресурсы MCP.

Этот инструмент поддерживается для обратной совместимости с клиентами, которые не поддерживают ресурсы MCP или resource_reader_tool.

Инструмент Matrix

Вычисляет время и расстояние в пути между несколькими точками с помощью Mapbox Matrix API. Возможности:

• Эффективные вычисления маршрутов «один ко многим», «многие к одному» и «многие ко многим»
• Поддержка разных профилей передвижения (driving-traffic, driving, walking, cycling)
• Указание времени отправления для вычислений с учётом дорожной обстановки
• Сводная информация о маршруте с показателями расстояния и продолжительности
• Настройка стороны подъезда (curb/unrestricted) и диапазона допустимых азимутов отправления

Инструмент Static image

Создаёт статические изображения карт с помощью Mapbox static image API. Возможности:

• Пользовательские стили карт (улицы, природа, спутник и т. д.)
• Настраиваемые размеры изображения и уровни масштабирования
• Поддержка нескольких маркеров с пользовательскими цветами и подписями
• Возможность наложения полилиний и полигонов
• Автоматическая подгонка под заданные координаты

Инструмент Category search

Выполняет поиск по категориям с помощью Mapbox Search Box category search API. Возможности:

• Поиск точек интереса по категориям (рестораны, отели, автозаправочные станции и т. д.)
• Фильтрация по географической близости
• Настраиваемое ограничение количества результатов
• Подробные метаданные для каждого результата
• Поддержка нескольких языков

Инструмент Reverse geocoding

Выполняет обратное геокодирование с помощью Mapbox geocoding V6 API. Возможности:

• Преобразование географических координат в понятные человеку адреса
• Настраиваемый уровень детализации (улица, район, город и т. д.)
• Фильтрация результатов по типу (адрес, точка интереса, район и т. д.)
• Поддержка нескольких языков
• Подробная информация о местоположении и его окружении

Инструмент Ground location

За один вызов отвечает на вопросы вроде «что находится рядом с этой координатой»: возвращает название места, ближайшие точки интереса и доступность с учётом времени в пути на основе актуальных данных Mapbox с указанием источников. Используйте его вместо последовательного вызова reverse_geocode_tool и веб-поиска.

Возможности:

• Классифицирует запрос (маршрутизация, контекст района, поиск точек интереса или регион/доступность) и получает только релевантные данные
• Поиск ближайших точек интереса по категории, если он запрошен
• Сводка доступности с учётом времени в пути (на основе изохрон)
• Возвращает ссылку render_map_tool с местоположением, подтверждённым данными, и нанесёнными на карту ближайшими точками интереса

Пример использования: «В каком районе находится эта координата и есть ли поблизости кофейни?»

Инструмент Place details

Получает подробную информацию о конкретном месте по его идентификатору Mapbox: фотографии, часы работы, рейтинги, номера телефонов и URL-адреса веб-сайтов. Используйте после search_and_geocode_tool, category_search_tool или reverse_geocode_tool, чтобы получить больше сведений о конкретном результате.

Пример использования: «Расскажи подробнее о первом результате с кофейней — часы работы, номер телефона и веб-сайт»

Инструмент Directions

Получает маршруты с помощью Mapbox Directions API. Возможности:

• Поддержка разных профилей маршрутизации: автомобиль (с учётом текущей или обычной дорожной обстановки), пешком и на велосипеде
• Маршрут через несколько промежуточных точек (2–25 пар координат)
• Возможность построения альтернативных маршрутов
• Аннотации маршрута (расстояние, продолжительность, скорость, загруженность дорог)
• Параметры планирования:
  • Будущее время отправления (depart_at) для профилей driving и driving-traffic
  • Желаемое время прибытия (arrive_by) только для профиля driving
• Оптимизации для отдельных профилей:
  • Автомобиль: ограничения по габаритам транспортного средства (высота, ширина, вес)
• Параметры исключения участков маршрута:
  • Общие исключения: паромные маршруты, платные дороги с оплатой только наличными
  • Исключения для автомобиля: платные дороги, автомагистрали, грунтовые дороги, туннели, государственные границы, границы штатов
  • Исключение заданных точек (до 50 географических точек, которых следует избегать)
• Формат вывода геометрии GeoJSON

Инструмент Isochrone

Вычисляет области, достижимые из заданного местоположения за указанное время, с помощью Mapbox Isochrone API. Возможности:

• Поддержка разных профилей передвижения (автомобиль, пешком, на велосипеде)
• Настраиваемое время или расстояние в пути
• Построение нескольких контуров (например, для интервалов 15, 30 и 45 минут)
• Возможность указать время отправления или прибытия
• Настройка цвета для визуализации

Инструмент Search and geocode

Использует конечную точку Mapbox Search Box Text Search API для поиска и геокодирования точек интереса, адресов, мест и других объектов, поддерживаемых этим API. Этот инструмент объединяет функции, которые в предыдущих версиях этого MCP-сервера предоставлялись инструментами ForwardGeocodeTool и PoiSearchTool.

Инструмент Map matching

Привязывает GPS-треки к дорожной сети с помощью Mapbox Map Matching API. Возможности:

• Преобразование зашумлённых GPS-треков в точные маршруты по дорожной сети
• Поддержка разных профилей передвижения (driving, driving-traffic, walking, cycling)
• Обработка до 100 пар координат в одном запросе
• Возможность указать временные метки для повышения точности на основе скорости
• Настраиваемые радиусы привязки для разных уровней качества GPS
• Аннотации маршрута (ограничения скорости, расстояние, продолжительность, загруженность дорог)
• Несколько форматов вывода геометрии (GeoJSON, polyline)

Пример использования: «Очисти этот GPS-трек и привяжи его к дорогам: [координаты с временными метками]»

Инструмент Optimization

Находит оптимальный маршрут через несколько мест с помощью Mapbox Optimization API. Возможности:

• Решение задачи коммивояжёра (TSP) для 2–12 мест
• Поддержка разных профилей передвижения (driving, driving-traffic, walking, cycling)
• Гибкая настройка начальной и конечной точек
• Оптимизация кольцевого маршрута или поездки в одну сторону
• Пошаговые инструкции по навигации (необязательно)
• Аннотации маршрута (расстояние, продолжительность, скорость)
• Несколько форматов вывода геометрии (GeoJSON, polyline)

Пример использования: «Найди оптимальный маршрут через эти 5 остановок: [список адресов или координат]»

Примечание: Доступна версия API V2 с расширенными возможностями (временные окна, ограничения по вместимости, несколько транспортных средств), но для неё требуется доступ к бета-версии. Реализация V2 включена в кодовую базу, но по умолчанию не зарегистрирована.

Инструмент Feedback

Отправляет разработчику отзыв пользователя о приложении или агенте через Mapbox Feedback API (Public Preview). Отзыв сохраняется в аккаунте владельца токена доступа. Поэтому, если вы создадите приложение или агента на этом сервере со своим токеном, отзывы пользователей будут поступать в ту же ленту, что и отчёты Feedback Agent ваших приложений, и вы сможете просматривать их в Feedback Explorer. Этот инструмент не сообщает о проблемах в Mapbox. Как и Feedback Agent, он предназначен для сбора любых отзывов о вашем продукте, которые помогают понять потребности пользователей, например:

• Место, которое закрылось, указано неверно или отмечено не там
• Место или адрес, который не удаётся найти
• Закрытая дорога, неверное ограничение скорости или неправильные данные о пробках
• Маршрут с запрещённым поворотом или въездом либо маршрут отсутствует
• Что-то связанное с самим приложением, например ошибка или предложение (application_issue)

Инструмент отправляет текст отзыва, категорию и местоположение, а затем возвращает идентификатор и статус записи. Местоположение необязательно, если отзыв не касается места; API требует его, поэтому инструмент передаёт координаты 0, 0, как пока рекомендует команда Feedback API. Ничего не отправляется без согласия пользователя: клиенты с поддержкой elicitation сначала показывают запрос на подтверждение, а в остальных случаях описание инструмента просит модель подтвердить отправку в чате.

Во время Public Preview Feedback API предоставляется бесплатно. После выхода в General Availability Feedback Agent будет взимать $0.02 за каждый отзыв. Чтобы не отправлять одну и ту же проблему дважды, перед отправкой инструмент проверяет собственные отчёты аккаунта за последние 30 дней. Если в той же категории есть отчёт в радиусе 50 м, который всё ещё ожидает рассмотрения (отзывы без местоположения не проверяются), инструмент возвращает этот отчёт вместо отправки нового. Feedback API показывает только собственные отчёты аккаунта, поэтому отчёты других аккаунтов обнаружить не удастся. send_anyway: true пропускает проверку, если пользователь говорит, что у него другая проблема.

Требования: для отправки токену доступа необходима область user-feedback:write, а для проверки дубликатов — user-feedback:read. Без области записи инструмент возвращает соответствующую ошибку. Без области чтения он отправляет отзыв без проверки и сообщает об этом в результате. Чтобы исключить инструмент, запустите сервер с --disable-tools feedback_tool.

Пример использования: «Blue Bottle на Mint St закрылась в прошлом году. Можешь отправить отзыв об этом?»

Инструмент Report

Отправляет команде Mapbox, которая разрабатывает сервер Mapbox MCP, отзыв о самом сервере: об ошибке, неверном или непонятном результате инструмента, отсутствующей возможности или предложении. Отзыв регистрируется от имени самого Mapbox, а не вашего аккаунта, поэтому дополнительная область токена не нужна. После отправки его нельзя просмотреть или отозвать. Этот инструмент не предназначен для сообщений о неверных данных карты, местах или маршрутах.

Сервер добавляет в конец текста свою версию, название и версию клиента, а также инструмент, к которому относится отзыв. Ничего не отправляется без согласия пользователя: клиенты с поддержкой elicitation сначала показывают запрос на подтверждение, а в остальных случаях описание инструмента просит модель подтвердить отправку в чате.

Инструмент использует конечную точку, добавленную командой Feedback API для команды mapbox report в Mapbox CLI. Чтобы исключить инструмент, запустите сервер с --disable-tools report_tool.

Пример использования: «Карта не отобразила ни одну из моих изохрон. Можешь сообщить об этом команде Mapbox MCP?»

Инструмент List public tokens

Выводит список общедоступных токенов аккаунта (pk.) для агента, который создаёт веб-страницу или приложение вне чата и загружает Mapbox GL JS либо вызывает API Mapbox из браузера. В чате render_map_tool не требует токена. Для каждого токена указываются его имя, статус токена по умолчанию, ограничения URL и области.

Передайте site_url (адрес, по которому будет работать страница), и инструмент порекомендует токен с ограничением для этого URL, если такой есть в аккаунте. В противном случае он порекомендует общедоступный токен по умолчанию и сообщит, что для опубликованного сайта следует использовать токен с ограничением по URL, добавив ссылку для его создания. Любой, кто скопирует общедоступный токен без ограничений, сможет им пользоваться, а расходы будут списываться с аккаунта.

Инструмент никогда не возвращает секретные или временные токены и не может создавать токены (для этого требуется tokens:write; это делает команда create_token_tool сервера DevKit).

Требования: для получения списка необходима область tokens:read — та же, которую уже использует карта в чате для поиска общедоступного токена по умолчанию. Если используется токен доступа pk. или при получении списка возникает ошибка на собственном MAPBOX_ACCESS_TOKEN сервера, а MAPBOX_PUBLIC_TOKEN задан, инструмент возвращает этот токен. Вызывающий объект с собственным токеном bearer (размещённый сервер) никогда не получает MAPBOX_PUBLIC_TOKEN, а токен с ограничениями для других URL никогда не рекомендуется. Чтобы исключить инструмент, запустите сервер с --disable-tools list_public_tokens_tool.

Пример использования: «Создай одностраничный сайт с картой Mapbox, на которой отмечены три наших магазина».

Разработка

Проверка сервера

Использование Node.js

# Run the built image
npm run inspect:build

Использование Docker

# Build the Docker image
docker build -t mapbox-mcp-server .

# Run and inspect the server
npx @modelcontextprotocol/inspector docker run -i --rm --env MAPBOX_ACCESS_TOKEN="YOUR_TOKEN" mapbox-mcp-server

Создание нового инструмента

npx plop create-tool
# provide tool name without suffix (e.g. Search)

Выпуск новой версии

# 1. Bump version in package.json
npm version <new-version> --no-git-tag-version

# 2. Sync version to manifest.json and server.json
npm run sync-manifest

# 3. Prepare CHANGELOG (replaces "Unreleased" with version and date)
npm run changelog:prepare-release <new-version>

# 4. Update package-lock.json
npm install

# 5. Review changes, then commit and tag
git add package.json package-lock.json manifest.json server.json CHANGELOG.md
git commit -m "Release v<new-version>"
git tag v<new-version>
git push && git push --tags

Важно: процесс публикации проверяет, что версии package.json и server.json совпадают с версией выпуска. Если пропустить обновление версии или синхронизацию манифеста, публикация завершится ошибкой.

Трассировка OpenTelemetry

Этот сервер MCP включает комплексную трассировку OpenTelemetry для наблюдаемости в рабочей среде:

Быстрая демонстрация

# 1. Copy the example configuration
cp .env.example .env

# 2. Edit .env to add your MAPBOX_ACCESS_TOKEN and configure tracing

# 3. Start Jaeger for local development
npm run tracing:jaeger:start

# 4. Run the server (it will automatically use .env configuration)
npm run inspect:build

# 5. View traces at http://localhost:16686

# 6. Stop Jaeger when done
npm run tracing:jaeger:stop

Примечание: при запуске сервер автоматически загружает конфигурацию из файла .env. Файл .env.example содержит примеры конфигурации для нескольких платформ наблюдаемости.

Поддерживаемые платформы наблюдаемости

В .env.example включены примеры конфигурации для следующих платформ:

Облачные провайдеры:

• ☁️ AWS X-Ray
• ☁️ Azure Monitor (Application Insights)
• ☁️ Google Cloud Trace

SaaS-платформы:

• 📊 Datadog
• 📊 New Relic
• 📊 Honeycomb
• 📊 Любой бэкенд, совместимый с OTLP

Конфигурация для рабочей среды

Полные инструкции по настройке, включая следующие темы, см. в docs/tracing.md:

• 🔧 Руководства по настройке для конкретных платформ
• 📊 Настройка аутентификации и конечных точек
• 🎯 Пользовательские атрибуты трассировки и контекст
• 🚀 Оптимизация производительности (минимальные накладные расходы)
• 🔍 Устранение неполадок и отладка

Возможности трассировки:

• ✅ Трассировка загрузки конфигурации (загрузка файла .env)
• ✅ Автоматическая трассировка выполнения инструментов
• ✅ Инструментирование HTTP-запросов с идентификаторами корреляции CloudFront
• ✅ Настраиваемые экспортёры (console, OTLP)
• ✅ С учётом требований безопасности (защита данных, проверка JWT)
• ✅ Готовность к рабочей среде (нагрузка на ЦП <1%)

Участие в разработке

Мы приветствуем вклад в разработку сервера Mapbox MCP! Перед отправкой pull request прочитайте CONTRIBUTING.md.

Полный перечень стандартов и рекомендаций:

• CONTRIBUTING.md — начало работы, процесс PR, краткий справочник
• Стандарты разработки (docs/engineering_standards.md) — полные стандарты качества кода, тестирования, документации и совместной работы
• Руководство по Claude Code (CLAUDE.md) — стандарты и шаблоны для участников, использующих Claude Code
• Инструкции для ИИ-агентов (AGENTS.md) — руководство для других ИИ-помощников по программированию (Cursor, Continue, Aider и т. д.)
• Рекомендации по GitHub Copilot — лучшие практики ответственного использования GitHub Copilot

Быстрый старт для участников

1. Создайте форк репозитория и клонируйте его
2. Установите зависимости: npm install
3. Внесите изменения в соответствии с нашими стандартами кодирования
4. Запустите тесты и линтер: npm test && npm run lint
5. Добавьте тесты для новых функций
6. Отправьте pull request с чётким описанием

Все изменения должны пройти проверки CI и проверку кода. Подробные требования см. в docs/engineering_standards.md.

Использование данных и конфиденциальность

Какие данные отправляются в API Mapbox

При использовании инструментов сервера MCP следующие данные отправляются напрямую из вашей среды в API Mapbox:

• Инструменты геокодирования: текст адреса или местоположения, координаты, фильтры по стране и региону
• Инструменты поиска: поисковые запросы, координаты местоположения для определения близости, фильтры по категориям
• Инструмент маршрутизации: начальные и конечные координаты, промежуточные точки, параметры маршрутизации, ограничения для транспортных средств
• Инструмент матрицы: несколько пар координат, профиль передвижения, время отправления
• Инструмент статической карты: координаты, уровень масштабирования, параметры оформления, сведения о маркерах
• Инструмент изохрон: координаты начальной точки, параметры времени или расстояния, профиль передвижения

Ваша конфиденциальность

• Локальное выполнение: все вызовы API выполняются напрямую из вашей среды к API Mapbox
• Безопасность токена: ваш токен API Mapbox остаётся на локальном компьютере и никогда не передаётся этому серверу MCP и не сохраняется им
• Данные не сохраняются: этот сервер MCP не хранит, не регистрирует и не собирает ваши данные или запросы к API
• Прямое взаимодействие: между вами и API Mapbox нет промежуточного сервера

Использование данных третьими сторонами

• Политика конфиденциальности Mapbox регулирует обработку данных, отправляемых в API: https://www.mapbox.com/legal/privacy/
• Использование API: ко всем запросам, отправляемым через эти инструменты, применяются стандартные условия использования API Mapbox
• Хранение данных: сведения о правилах хранения данных см. в документации Mapbox

Поддержка и контакты

Проблемы с сервером MCP

• Электронная почта: mcp-feedback@mapbox.com
• Проблемы на GitHub: Сообщить об ошибках и запросить новые функции

Вопросы об API Mapbox

• Поддержка Mapbox: https://support.mapbox.com/
• Документация: https://docs.mapbox.com/
• Статус API: https://status.mapbox.com/

Обязательства по сопровождению

Этот сервер MCP официально сопровождается компанией Mapbox, Inc. Мы обеспечиваем:

• Регулярные обновления с поддержкой новых функций API Mapbox
• Исправления ошибок и обновления безопасности
• Совместимость с последними версиями протокола MCP
• Поддержку сообщества через GitHub Issues

---

Лицензия MIT