Desirepath

Urban street network analysis as an MCP server and CLI.

An LLM or CLI tool can ask: route between two points, find missing links, measure circuity, compute isochrones, compare cities, render interactive maps. Desirepath is a typed MCP interface over OSMnx and Momepy, with 20 tools and 9 resources.

Install

Requires Python 3.12+ and uv.

git clone https://github.com/yourname/desirepath
cd desirepath
uv sync

Quickstart

# Check environment
uv run desirepath doctor

# Network stats for any place
uv run desirepath stats "Piedmont, California, USA"

# Compare two cities
uv run desirepath compare "Amsterdam, Netherlands" "Houston, Texas, USA"

# Start the MCP server
uv run desirepath serve --place "Amsterdam, Netherlands" --name amsterdam

Sample stats output:

{
  "n": 388,
  "m": 916,
  "edge_length_avg": 106.4,
  "streets_per_node_avg": 2.887,
  "circuity_avg": 1.065
}

Connect to Claude

Claude Code: add to .mcp.json at the project root:

{
  "mcpServers": {
    "desirepath": {
      "command": "uv",
      "args": ["run", "desirepath", "serve"],
      "cwd": "/path/to/desirepath",
      "type": "stdio"
    }
  }
}

Claude Desktop: add to ~/Library/Application Support/Claude/claude_desktop_config.json:

{
  "mcpServers": {
    "desirepath": {
      "command": "uv",
      "args": [
        "run", "--project", "/path/to/desirepath",
        "desirepath", "serve",
        "--graphml", "/path/to/my_city.graphml",
        "--name", "my_city"
      ]
    }
  }
}

Claude Desktop's sandbox blocks Overpass at runtime. Download a graph first with desirepath serve --place ..., call save_graph to write it to disk, then use --graphml on subsequent starts.

MCPJam Inspector: renders map_graph, map_route, and map_isochrone as inline Leaflet maps:

npx @mcpjam/inspector@latest --config mcpjam.json --server desirepath

Tools

All routing coordinates are in lng, lat order.

Graph

Routing

Stats

Basic stats, orientation entropy, street hierarchy, and degree distribution are resources, not tools. Read them at graph://{name}/stats and graph://{name}/street-hierarchy without a tool call.

Morphology

morphology(metrics=[...]) computes any combination of:

• linearity: edge straightness (0 to 1)
• sinuosity: inverse of linearity; top 10 most winding streets
• connectivity: meshedness coefficient; near 1 = grid, near 0 = tree
• clustering: squares clustering coefficient (how grid-like at the local scale)
• intersection_types: dead-end / 3-way / 4-way-plus fractions

Features

get_features(source, tags) fetches OSM features from Overpass by point, bbox, or place name. Times out after 25 seconds; use specific tag values.

Enrichment

enrich_graph(speeds, travel_times, bearings, grades) adds computed attributes to graph edges in a single call.

Map

Renders inline in MCPJam Inspector. Saves HTML to ~/Downloads/ on other hosts.

Compare

compare_graphs produces a side-by-side JSON summary of two loaded graphs.

Optional tools

Optional tools register automatically when their dependency is installed. Run uv run desirepath doctor to see what is present.

Resources

Resources are read directly by the agent without a tool call.

Programmatic use

import osmnx as ox
from desirepath import mount

G = ox.graph_from_place("Piedmont, California, USA", network_type="drive")
G = ox.add_edge_speeds(G)
G = ox.add_edge_travel_times(G)

server = mount(G, name="piedmont")
server.run()

mount(G) accepts any nx.MultiDiGraph and returns a FastMCP server. Use server.run_http_async() for HTTP transport.

Attribution

• Street network data: OpenStreetMap contributors (ODbL)
• Graph construction: OSMnx by Geoff Boeing
• Urban morphology: Momepy by Martin Fleischmann
• Spatial statistics: PySAL