osm-mcp

Сервер MCP для OpenStreetMap: геокодирование, расстояния и время в пути пешком/на автомобиле/на велосипеде, оптимизация маршрута с несколькими остановками, изохроны и поиск POI — создан для планирования поездок с помощью ИИ-ассистентов.

11 инструментов, все только для чтения. Все бэкенды — бесплатные публичные сервисы OpenStreetMap; ключ API не требуется. Ключ OpenRouteService можно указать опционально для смены движка маршрутизации.

📖 Полная документация: https://osm-mcp.ni-c.de

Зачем ещё один MCP-сервер для OSM?

• Корректные маршруты для пеших и велосипедных прогулок. Публичные демо-серверы OSRM игнорируют сегмент профиля внутри пути URL OSRM и всегда возвращают маршруты для автомобиля, если не используются префиксы путей FOSSGIS routed-foot / routed-bike / routed-car. Большинство существующих MCP-серверов для OSM делают это неправильно и молча возвращают время вождения для пеших запросов. Этот сервер использует префиксы, и его живой smoke-тест проверяет, что пешие маршруты значительно медленнее автомобильных.

• Соответствие политике по построению. Ограничение скорости для каждого сервиса (Nominatim и OSRM: 1 запрос/секунду), идентифицирующий User-Agent для каждого запроса (требуется политикой использования Nominatim), кэширование ответов, ограниченная конкурентность Overpass (2 слота) и автоматическое переключение на зеркало Overpass при 429/5xx.

• Поддержка Photon. Опциональное геокодирование, устойчивое к опечаткам, с помощью komoot's Photon, которое предназначено для интерактивного использования — лучше подходит для поиска, управляемого LLM, чем постоянные запросы к Nominatim.

Related MCP server: Geo MCP Worker

Требования

• Node.js ≥ 22

• Доступ в Интернет к публичным сервисам OpenStreetMap (см. таблицу ниже)

Конфигурация

Все переменные опциональны — сервер работает «из коробки».

Установка

claude mcp add osm -- npx -y osm-mcp

Claude Desktop (claude_desktop_config.json):

{
  "mcpServers": {
    "osm": {
      "command": "npx",
      "args": ["-y", "osm-mcp"]
    }
  }
}

Codex (~/.codex/config.toml):

[mcp_servers.osm]
command = "npx"
args = ["-y", "osm-mcp"]

Контейнер (мультиархитектурный, с SBOM и подтверждением сборки):

docker run -i --rm ghcr.io/ni-c/osm-mcp

-i обязателен — протокол работает через stdin и stdout. Нет порта для публикации. Другие рецепты для клиентов — в руководстве по клиентам.

Инструменты

Каждый ввод места принимает либо название/адрес (автоматически геокодируется), либо буквальные координаты в формате "lat,lon".

Политика использования и атрибуция

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

• Данные: © участники OpenStreetMap, лицензия ODbL 1.0.

• Nominatim: макс. 1 запрос/секунду, обязателен идентифицирующий User-Agent, результаты кэшируются (политика).

• OSRM / Valhalla (FOSSGIS): разумное, некоммерческое использование; макс. 1 запрос/секунду (о сервисе).

• Overpass: ~2 одновременных слота на IP, <10 000 запросов/день (вики).

• Photon: добросовестное использование (photon.komoot.io).

Для интенсивного или коммерческого использования разверните сервисы самостоятельно и укажите переменные *_BASE_URL на ваши экземпляры.

Безопасность

• Все инструменты только для чтения; сервер никогда не записывает данные в OpenStreetMap.

• Никакие учётные данные не требуются; опциональный ORS_API_KEY удаляется из окружения процесса после загрузки и скрывается в сообщениях об ошибках.

• Контент из OSM (названия, адреса, теги) помечается как ненадёжные данные в результатах инструментов, чтобы модель обрабатывала их как данные, а не инструкции.

• Тела ошибок вышестоящих сервисов усекаются, а HTML-страницы ошибок отбрасываются до того, как они попадут в контекст модели.

• Перенаправления никогда не выполняются; все запросы имеют тайм-аут.

Разработка

npm install
npm run lint          # eslint + prettier
npm test              # unit tests (all upstream APIs mocked)
npm run test:coverage
npm run build
npm run smoke         # opt-in LIVE test against the real public services

Релиз

Управляется тегами, без ручного шага публикации:

1. Перенесите записи [Unreleased] в новый раздел ## [x.y.z] - YYYY-MM-DD в CHANGELOG.md и обновите package.json.

2. npm run lint && npm run build && npm run test:coverage.

3. Сделайте коммит, затем подписанный аннотированный тег: git tag -s vx.y.z -m "vx.y.z".

4. git push origin main vx.y.z.

Затем release.yml запускает тесты, публикует в npm с подтверждением через Trusted Publishing (без участия токена), создаёт релиз на GitHub из раздела CHANGELOG и публикует в реестр MCP как io.github.ni-c/osm-mcp. ci.yml отправляет мультиархитектурный образ в GHCR по тому же тегу.

Если шаг с реестром не удался, исправьте проблему в main и запустите workflow Publish to MCP Registry — не запускайте задачу с тегом повторно, так как она будет использовать старую версию кода.

Лицензия

MIT