Mapbox MCP Server

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

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

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

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

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

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

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

Хостинговый MCP-эндпоинт

Для быстрого старта можно воспользоваться нашим хостинговым MCP-эндпоинтом:

Эндпоинт: https://mcp.mapbox.com/mcp

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

Как получить access token Mapbox:

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

Подробнее о токенах доступа Mapbox см. в документации Mapbox по access token.

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

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

Claude Desktop Setup — настройка Claude Desktop для работы с этим MCP-сервером
Goose Setup — настройка фреймворка AI-агентов Goose
VS Code Setup — настройка среды разработки в Visual Studio Code
Cursor AI IDE Setup — настройка среды разработки в Cursor AI IDE
Smolagents Integration — пример подключения AI-агентов Smolagents к инструментам Mapbox
Importing Tools Directly — использование инструментов Mapbox в ваших собственных приложениях без запуска MCP-сервера
render_map_tool Guide — примитив визуализации карт: полная схема payload и способ рендерить собственные данные автономно, без других инструментов Mapbox
Elicitations — как search_and_geocode_tool и directions_tool просят пользователя уточнить результаты или выбрать маршрут и как они корректно отступают, когда клиент это не поддерживает

Примеры промптов

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

Привязка к месту (Location Grounding)

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

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

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

Поиск мест

«Найди кофейни в пределах пешей доступности от Empire State Building»
«Хочу поехать из Seattle в Portland — есть ли Starbucks по пути?»
«Покажи заправки вдоль маршрута из Boston в New York»
«Какие рестораны есть рядом с Times Square?»

Навигация и путешествия

«Построй автомобильный маршрут из LAX в Hollywood с учётом текущего трафика»
«Сколько времени займёт пешая прогулка из Central Park в Times Square?»
«Рассчитай время поездки на такси от моего отеля (Four Seasons) до JFK Airport в час пик»

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

«С помощью инструмента рендеринга карт Mapbox покажи маршрут от Golden Gate Bridge до Union Square в San Francisco» — отрисует живой интерактивный маршрут на настоящей карте Mapbox
«Создай изображение карты с маршрутом от Golden Gate Bridge до Fisherman's Wharf и маркерами в обеих точках»
«Покажи спутниковый снимок Manhattan с отмеченными ключевыми достопримечательностями»
«Сгенерируй карту со всеми Starbucks в радиусе одной мили от центра Seattle»
«Покажи заполненный полигон по этим координатам: [...], с маркером с подписью "Warehouse" в [...]» — отрисует ваш собственный GeoJSON напрямую через render_map_tool, без других инструментов Mapbox

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

«Покажи зоны, достижимые за 30 минут на машине от центра Portland»
«Рассчитай матрицу времени в пути между этими 3 отелями (Marriott, Sheraton и Hilton) и конференц-центром в Denver»
«Найди оптимальный маршрут посещения этих 3 достопримечательностей (Golden Gate, Musical Stairs и Fisherman's Wharf) в San Francisco»
«Оптимизируй маршрут доставки по этим 8 адресам: [список адресов]»

GPS и сопоставление маршрутов

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

Офлайн-геопространственные вычисления

«Каково расстояние в милях между этими двумя координатами?»
«Рассчитай площадь этого полигона в квадратных километрах»
«Находится ли точка 37.7749°N, 122.4194°W внутри этого полигона зоны обслуживания?»
«Каков азимут из San Francisco в New York?»
«Найди среднюю точку между London и Paris»
«Создай буферную зону в 5 миль вокруг этой локации»
«Рассчитай центроид этой границы района»
«Какова ограничивающая рамка для этих координат маршрута?»
«Упрости этот сложный полигон, чтобы уменьшить число точек»

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

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

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

Ресурсы

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

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

Ресурс Mapbox Categories

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

Ресурс даёт доступ к полному списку доступных идентификаторов категорий для использования с инструментом поиска по категориям. Категории позволяют фильтровать результаты поиска по типу (например, «restaurant», «hotel», «gas_station»).

Примеры:

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 — единственный примитив визуализации на сервере. В поддерживаемых клиентах он отрисовывается по протоколу MCP Apps (@modelcontextprotocol/ext-apps) как автономная HTML-панель прямо в чате, с переключателем полноэкранного режима:

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

Чтобы воспользоваться им, не нужны никакие другие инструменты этого сервера. Кроме того, render_map_tool принимает GeoJSON, составленный вручную, — ваши собственные полигоны, маркеры и маршруты — без зависимости от directions_tool, isochrone_tool или каких-либо других вызовов Mapbox API. Схему полезной нагрузки и полный автономный пример смотрите в полном руководстве по 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 или любой другой клиент с поддержкой ресурсов
❌ Оставьте неустановленной, если сомневаетесь (большинство клиентов поддерживают ресурсы)

Инструменты

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

Resource Reader Tool

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

Параметры:

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

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

Чтение категорий по умолчанию: {"uri": "mapbox://categories"}
Чтение японских категорий: {"uri": "mapbox://categories/ja"}

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

Офлайн-геопространственные инструменты

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

Distance Tool

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

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

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

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

Points Within Polygon Tool

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

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

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

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

Destination Tool

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

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

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

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

Bearing Tool

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

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

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

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

Midpoint Tool

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

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

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

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

Centroid Tool

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

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

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

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

Area Tool

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

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

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

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

Bounding Box Tool

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

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

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

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

Buffer Tool

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

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

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

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

Simplify Tool

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

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

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

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

Length Tool

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

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

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

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

Convex Tool

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

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

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

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

Nearest Point Tool

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

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

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

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

Nearest Point on Line Tool

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

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

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

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

Инструменты объединения, пересечения и разности

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

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

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

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

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

Инструмент списка категорий (устаревший)

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

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

Инструмент Matrix

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

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

Инструмент статического изображения

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

Собственные стили карты (streets, outdoors, satellite и т. д.)
Настраиваемые размеры изображения и уровни масштабирования
Поддержка нескольких маркеров с настраиваемыми цветами и подписями
Опции наложения, включая полилинии и полигоны
Автоматическая подгонка под указанные координаты

Инструмент поиска по категориям

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

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

Инструмент обратного геокодирования

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

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

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

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

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

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

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

Инструмент сведений о месте

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

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

Инструмент маршрутов

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

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

Инструмент изохрон

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

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

Инструмент поиска и геокодирования

Использует конечную точку Mapbox Search Box Text Search API, чтобы обеспечить поиск и геокодирование POI, адресов, мест и любых других типов, поддерживаемых этим API.

Этот инструмент объединяет функциональность, которую ранее предоставляли ForwardGeocodeTool и PoiSearchTool (в более ранних версиях этого MCP-сервера), в один инструмент.

Инструмент сопоставления с картой

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

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

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

Инструмент оптимизации

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

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

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

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

Разработка

Инспектирование сервера

Использование 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)

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

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

4. Update package-lock.json

npm install

5. Проверьте изменения, затем закоммитьте и поставьте тег

git add package.json package-lock.json manifest.json server.json CHANGELOG.md git commit -m "Release v" git tag v git push && git push --tags">

# 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, включая:

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

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

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

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

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

Полные стандарты и рекомендации:

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

Быстрый старт для контрибьюторов

Сделайте форк репозитория и клонируйте свой форк
Установите зависимости: npm install
Внесите изменения, следуя нашим стандартам кодирования
Запустите тесты и линтинг: npm test && npm run lint
Добавьте тесты для любой новой функциональности
Отправьте pull request с понятным описанием

Все вклады должны проходить наши CI-проверки и процесс code review. Подробные требования см. в docs/engineering_standards.md.

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

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

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

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

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

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

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

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

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

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

Email: mcp-feedback@mapbox.com
GitHub Issues: Сообщить об ошибках и предложить функции

Вопросы по Mapbox API

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

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

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

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

MIT License

Mapbox MCP Server

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

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

Хостинговый MCP-эндпоинт

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

Примеры промптов

Привязка к месту (Location Grounding)

Поиск мест

Навигация и путешествия

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

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

GPS и сопоставление маршрутов

Офлайн-геопространственные вычисления

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

Ресурсы

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

Ресурс Mapbox Categories

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

CLIENT_NEEDS_RESOURCE_FALLBACK

Инструменты

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

Resource Reader Tool

Офлайн-геопространственные инструменты

Distance Tool

Points Within Polygon Tool

Destination Tool

Bearing Tool

Midpoint Tool

Centroid Tool

Area Tool

Bounding Box Tool

Buffer Tool

Simplify Tool

Length Tool

Convex Tool

Nearest Point Tool

Nearest Point on Line Tool

Инструменты объединения, пересечения и разности

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

Инструмент списка категорий (устаревший)

Инструмент Matrix

Инструмент статического изображения

Инструмент поиска по категориям

Инструмент обратного геокодирования

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

Инструмент сведений о месте

Инструмент маршрутов

Инструмент изохрон

Инструмент поиска и геокодирования

Инструмент сопоставления с картой

Инструмент оптимизации

Разработка

Инспектирование сервера

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

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

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

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

2. Sync version to manifest.json and server.json

3. Prepare CHANGELOG (replaces "Unreleased" with version and date)

4. Update package-lock.json

5. Проверьте изменения, затем закоммитьте и поставьте тег

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

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

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

Конфигурация для продакшена

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

Быстрый старт для контрибьюторов

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

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

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

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

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

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

Вопросы по Mapbox API

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

Интерактивные предпросмотры карт (`render_map_tool`)