OpenRoute MCP

Servidor MCP para ajudar a planejar rotas usando OpenRouteService.org, para atividades como caminhadas ou mountain bike.

GitHub
2

Documentação

🗺️ OpenRoute MCP

PyPI - Version PyPI - Python Version Tests MCP registry

Servidor Model Context Protocol (MCP) para planejar rotas usando a OpenRouteService API, para atividades como trilhas ou mountain bike.

[!CAUTION]

AVISO: As rotas geradas por este serviço são fornecidas apenas para fins informativos e não são garantidas como seguras, legais ou adequadas para o uso pretendido. Sempre verifique as rotas de forma independente usando mapas oficiais, autoridades locais e condições atuais antes de tentar qualquer jornada. Os usuários assumem todos os riscos e responsabilidades pela sua segurança e conformidade com as leis e regulamentos locais.

[!TIP]

Copie todo o arquivo GPX retornado como parte dos resultados da chamada da ferramenta e use um serviço como o gpx.studio para carregar o arquivo GPX gerado em um mapa.

🛠️ Ferramentas disponíveis

  • 📍 Encontrar coordenadas possíveis para um local
    • Argumentos:
      • location (string): local para obter as coordenadas
    • Retorna: lista de 10 coordenadas com descrição disponível para permitir que o agente descubra a correta
  • 🏠 Encontrar locais possíveis (endereços) para determinadas coordenadas.
    • Argumentos:
      • lon (float): Longitude do local
      • lat (float): Latitude do local
    • Retorna: lista de objetos próximos às coordenadas fornecidas
  • 🗺️ Criar uma rota de um local de partida até um destino, opcionalmente com waypoints
    • Argumentos:
      • route_type (string): Tipo de rota, ex.: "cycling-mountain", "cycling-regular", "foot-hiking", "driving-car"
      • from_coordinates (list[float]): Local de partida como [longitude, latitude]
      • from_coordinates (list[float]): Local de destino como [longitude, latitude]
      • waypoints (list[list[float]]): lista opcional de coordenadas de waypoints como [[lon, lat], ...]
    • Retorna:
      • um arquivo de recurso contendo o GPX da rota (ex.: route://foot-hiking-98.gpx)
      • um arquivo de recurso contendo uma imagem PNG com a visualização da rota (ex.: route://foot-hiking-98.png)
      • um arquivo de recurso contendo uma visualização interativa HTML da rota (ex.: ui://foot-hiking-98.html) que pode ser aberta diretamente no seu navegador
  • 📌 Buscar Pontos de Interesse (POIs) em uma área
    • Argumentos:
      • bounding_box_coordinates (list[list[float]]): coordenadas que definem uma caixa delimitadora como [[min_lon, min_lat], [max_lon, max_lat]]
      • filters_name (list[string]): lista opcional de nomes para filtrar POIs, ex.: ["Posto de gasolina", "Restaurante"]
    • Retorna: informações dos POIs encontrados
  • 🔎 Buscar rotas conhecidas próximas a coordenadas de início e fim fornecidas, isso permite sugerir waypoints para passar por trilhas conhecidas ao criar uma rota. Atualmente funciona apenas na Suíça graças à Confederação Suíça api3.geo.admin.ch 🇨🇭
    • Argumentos:
      • route_type (string): Tipo de rota, ex.: "cycling-mountain", "cycling-regular", "foot-hiking", "driving-car"
      • from_coordinates (list[float]): Local de partida como [longitude, latitude]
      • from_coordinates (list[float]): Local de destino como [longitude, latitude]
    • Retorna: traçado de trilhas conhecidas e descrição quando disponível para ajudar o agente a construir uma boa rota
  • ⏱️ Calcula a área que pode ser alcançada dentro de um determinado tempo ou distância a partir de um ou mais pontos de partida.

    • Argumentos:

      • coordinates_list: 1 ou mais coordenadas para calcular a área alcançável a partir de [[lon, lat], ...]
      • route_type: Tipo de rota, ex.: "cycling-mountain", "cycling-regular", "foot-hiking", "driving-car"
      • range_type: Tipo de alcance, seja time (em segundos) ou distance (em metros)
      • area_range: valor máximo de alcance da análise em segundos para tempo e metros para distância. Ou uma lista separada por vírgulas de valores de alcance específicos

    • Retorna: informações da área alcançável no formato GeoJSON

🗃️ Recursos disponíveis

  • 🚏 Arquivos de rota
    • Padrão de URL: route://{filename}
    • Tipo: GPX (.gpx), HTML (.html) ou PNG (.png)
    • Descrição: Retorna um arquivo de rota gerado anteriormente pelo nome do arquivo.
    • Produzido por: ferramenta create_route_from_to

🔌 Conectar o cliente ao servidor MCP

Siga as instruções do seu cliente e use a URL /mcp do seu servidor implantado (ex.: http://localhost:8888/mcp)

Por exemplo, para o GitHub Copilot no VSCode, para adicionar um novo servidor MCP através da interface do VSCode:

  • Abra o painel lateral de chat (ctrl+shift+i ou cmd+shift+i) e certifique-se de que o modo esteja definido como Agent no canto inferior direito
  • Abra a paleta de comandos (ctrl+shift+p ou cmd+shift+p) e procure por MCP: Open User Configuration, isso abrirá um arquivo mcp.json

⌨️ Usar transporte stdio

[!IMPORTANT]

Faça login com o GitHub em openrouteservice.org e obtenha uma chave de API que você pode fornecer através da variável de ambiente OPENROUTESERVICE_API_KEY.

OPENROUTESERVICE_API_KEY=YYY uvx openroute-mcp

No arquivo mcp.json do VSCode você deve ter:

{
  "servers": {
    "openroute-mcp": {
      "command": "uvx",
      "args": [
        "openroute-mcp"
      ],
      "env": {
        "OPENROUTESERVICE_API_KEY": "YOUR_API_KEY"
      }
    }
  }
}

[!IMPORTANT]

Clique em Start logo acima de "openroute-mcp" para iniciar a conexão com o servidor MCP.

Você pode clicar no botão de chave inglesa e chave de fenda 🛠️ (Configure Tools...) para habilitar/desabilitar ferramentas específicas

Detalhes completos das opções de CLI:

usage: openroute-mcp [-h] [--http] [--port PORT] [--openroute-api OPENROUTE_API] [--openroute-api-key OPENROUTE_API_KEY]
                     [--data-folder DATA_FOLDER] [--no-save] [--no-img] [--no-html]

A Model Context Protocol (MCP) server for building routes using OpenRouteService.

options:
  -h, --help            show this help message and exit
  --http                Use Streamable HTTP transport
  --port PORT           Port to run the server on
  --openroute-api OPENROUTE_API
                        OpenRouteService API URL (default: https://api.openrouteservice.org)
  --openroute-api-key OPENROUTE_API_KEY
                        OpenRouteService API key (default: taken from env var OPENROUTESERVICE_API_KEY)
  --data-folder DATA_FOLDER
                        Folder to save generated routes
  --no-save             Don't save generated routes to disk (also disable image and HTML generation)
  --no-img              Do not add PNG image visualization of the routes to the response (image not supported by all LLMs)
  --no-html            Do not add HTML interactive map for routes to the response

🧑‍💻 Desenvolvimento

Consulte a página CONTRIBUTING.md para mais detalhes sobre como executar em desenvolvimento e contribuir.