OpenStreetMap

Servidor MCP OpenStreetMap (OSM)

Uma implementação de servidor MCP OpenStreetMap que aprimora as capacidades de LLMs com serviços baseados em localização e dados geoespaciais.

Demonstração

Otimização de Ponto de Encontro

Análise de Vizinhança

Busca de Estacionamento

Instalação

Em Hosts MCP como Claude Desktop, Cursor, Windsurf, etc.

• osm-mcp-server: O servidor principal, disponível para uso público.

  "mcpServers": {
    "osm-mcp-server": {
      "command": "uvx",
      "args": [
        "osm-mcp-server"
      ]
    }
  }
  

Recursos

Este servidor fornece aos LLMs ferramentas para interagir com dados do OpenStreetMap, permitindo aplicações baseadas em localização para:

• Geocodificar endereços e nomes de lugares em coordenadas
• Geocodificar reversamente coordenadas em endereços
• Encontrar pontos de interesse próximos
• Obter instruções de rota entre locais
• Buscar lugares por categoria dentro de uma caixa delimitadora
• Sugerir pontos de encontro ideais para várias pessoas
• Explorar áreas e obter informações abrangentes de localização
• Encontrar escolas e instituições educacionais próximas a um local
• Analisar opções de deslocamento entre casa e trabalho
• Localizar estações de carregamento de veículos elétricos com filtros de conector e potência
• Realizar análise de habitabilidade de vizinhança para imóveis
• Encontrar instalações de estacionamento com informações de disponibilidade e taxas

Componentes

Recursos

O servidor implementa recursos baseados em localização:

• location://place/{query}: Obter informações sobre lugares por nome ou endereço
• location://map/{style}/{z}/{x}/{y}: Obter blocos de mapa estilizados em coordenadas especificadas

Ferramentas

O servidor implementa várias ferramentas geoespaciais:

• geocode_address: Converter texto em coordenadas geográficas
• reverse_geocode: Converter coordenadas em endereços legíveis
• find_nearby_places: Descobrir pontos de interesse próximos a um local
• get_route_directions: Obter instruções passo a passo entre locais
• search_category: Encontrar lugares de categorias específicas em uma área
• suggest_meeting_point: Encontrar pontos de encontro ideais para várias pessoas
• explore_area: Obter dados abrangentes sobre uma vizinhança
• find_schools_nearby: Localizar instituições educacionais próximas a um local específico
• analyze_commute: Comparar opções de transporte entre casa e trabalho
• find_ev_charging_stations: Localizar infraestrutura de carregamento de veículos elétricos com filtros
• analyze_neighborhood: Avaliar habitabilidade de vizinhança para imóveis
• find_parking_facilities: Localizar opções de estacionamento próximas a um destino

Testes Locais

Executando o Servidor

Para executar o servidor localmente:

1. Instale o pacote em modo de desenvolvimento:

pip install -e .

2. Inicie o servidor:

osm-mcp-server

3. O servidor iniciará e aguardará solicitações MCP na entrada/saída padrão.

Testando com Clientes de Exemplo

O repositório inclui dois clientes de exemplo no diretório examples/:

Exemplo de Cliente Básico

client.py demonstra o uso básico do servidor OSM MCP:

python examples/client.py

Isso irá:

• Conectar-se ao servidor em execução local
• Obter informações sobre São Francisco
• Buscar restaurantes na área
• Recuperar dados abrangentes do mapa com acompanhamento de progresso

Exemplo de Integração com LLM

llm_client.py fornece uma classe auxiliar projetada para integração com LLM:

python examples/llm_client.py

Este exemplo mostra como um LLM pode usar o Assistente de Localização para:

• Obter informações de localização a partir de consultas de texto
• Encontrar pontos de interesse próximos
• Obter direções entre locais
• Encontrar pontos de encontro ideais
• Explorar vizinhanças

Escrevendo Seu Próprio Cliente

Para criar seu próprio cliente:

1. Importe o cliente MCP:

from mcp.client import Client

2. Inicialize o cliente com a URL do seu servidor:

client = Client("http://localhost:8000")

3. Invoque ferramentas ou acesse recursos:

# Example: Geocode an address
results = await client.invoke_tool("geocode_address", {"address": "New York City"})

Configuração do Claude Desktop para servidor local

No MacOS: ~/Library/Application\ Support/Claude/claude_desktop_config.json No Windows: %APPDATA%/Claude/claude_desktop_config.json

"mcpServers": {
  "osm-mcp-server": {
    "command": "uv",
    "args": [
      "--directory",
      "/path/to/osm-mcp-server",
      "run",
      "osm-mcp-server"
    ]
  }
}

Desenvolvimento

Compilação e Publicação

Para preparar o pacote para distribuição:

1. Sincronize as dependências e atualize o arquivo de bloqueio:

uv sync

2. Compile as distribuições do pacote:

uv build

Isso criará distribuições de código-fonte e wheel no diretório dist/.

3. Publique no PyPI:

uv publish

Nota: Você precisará definir as credenciais do PyPI por meio de variáveis de ambiente ou sinalizadores de comando.

Depuração

Como os servidores MCP são executados via stdio, a depuração pode ser desafiadora. Para a melhor experiência de depuração, recomendamos fortemente o uso do MCP Inspector.

Você pode iniciar o MCP Inspector via npm com este comando:

npx @modelcontextprotocol/inspector uv --directory /path/to/osm-mcp-server run osm-mcp-server

Ao iniciar, o Inspector exibirá uma URL que você pode acessar no seu navegador para começar a depurar.