urban-mcp

A Model Context Protocol (MCP) server for urban planning, mobility and spatial statistics. It gives AI agents (Claude Desktop, Claude Code and any other MCP client) 24 tools for accessibility (2SFCA, gravity, 15-minute city, PTAL), multi-criteria siting (AHP, TOPSIS, MCLP), space syntax, landscape metrics, seismic screening, slope-aware routing and isochrones, and spatial statistics (Moran's I, LISA, Getis-Ord Gi*, GWR, Huff).

The methods come from three published, tested SDKs; this package is a thin, validated MCP layer over them:

Generic GIS MCP servers (e.g. gis-mcp, mcp-geo) cover geometry operations and file I/O; urban-mcp focuses on planning indicators and spatial statistics and returns analysis-ready summaries.

Installation

pip install urban-mcp          # Python >= 3.10
urban-mcp --list-tools         # check the install

Or run it without installing, with uv:

uvx urban-mcp --list-tools

Dependencies: mcp (official Python SDK, 2.x), planx-sdk, zero2route3d-sdk, geoai2analytics-sdk and NumPy/SciPy. No GDAL, GeoPandas or Shapely is needed.

Connecting a client

Claude Code

claude mcp add urban-mcp -- uvx urban-mcp
# with file output and OpenStreetMap downloads enabled:
claude mcp add urban-mcp -- uvx urban-mcp --output-dir ./urban_outputs --allow-network

Claude Desktop

Add to claude_desktop_config.json (Settings > Developer > Edit Config):

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

With a pip install, use "command": "urban-mcp", "args": [] instead. To let the server save results, add "--output-dir", "/path/to/folder" to args.

Other clients / HTTP

Any MCP client that launches a stdio server can run urban-mcp. For a network service use streamable HTTP (bound to localhost by default):

urban-mcp --transport streamable-http --host 127.0.0.1 --port 8000   # endpoint: /mcp

Options

Tools

Inputs are GeoJSON FeatureCollections (points; polygons are reduced to their area-weighted centroid), plain arrays and numbers, each described in the tool's JSON schema. Coordinates may be WGS84 lon/lat or projected metres: coordinate_system="auto" treats a layer as lon/lat when every coordinate lies within +-180/+-90 and projects it to a local plane in metres. Pass coordinate_system="projected" for projected data with small coordinate values (e.g. a local grid in metres near the origin). Routing tools need lon/lat.

Outputs are JSON objects with the SDK function used, a summary (counts, min/mean/max, class counts, top items) and, where it makes sense, a GeoJSON result that pairs each input geometry with the computed properties. Results are capped at --max-output-features and marked truncated: true with total_features.

Distances in the point-based tools (2SFCA, gravity, 15-minute city, MCLP, Huff) are straight-line. Use route_3d / isochrones_3d, or pass a network travel-time matrix to accessibility_2sfca_matrix, for network distances.

Resources and prompts

Example conversations

You: Here are our neighbourhood centroids with population and the GP clinics with doctor counts (two GeoJSON files). Who is underserved within 1.5 km?

Assistant calls accessibility_2sfca(demand_points=..., supply_points=..., demand_field="population", supply_field="doctors", cutoff_m=1500) and answers: "Median access is 0.42 doctors per 1 000 residents; 3 of 41 neighbourhoods (6 900 people) have no clinic within 1.5 km - all on the eastern edge. The population-weighted Gini is 0.38."

You: Is the rent level clustered? Use the census tracts layer.

Assistant runs the hot_spot_analysis prompt: global_moran_i (I = 0.41, p = 0.001), then local_moran_lisa and hotspot_gi_star, and reports 12 high-high tracts around the waterfront and 9 low-low tracts in the north, noting the FDR correction.

You: How much harder is the walk from the station to the hospital for a wheelchair user?

Assistant calls route_3d twice (profile="adult" and profile="wheelchair") on the street network and compares: "The direct route climbs 40 m over a steep hill street; the wheelchair route avoids it, 0.44 km longer (12.5 vs 8.1 min) and ADA-compliant."

You: We have 120 candidate parcels; pick 5 shelter sites that cover most residents within 500 m.

Assistant calls facility_siting_mclp(k=5, max_distance_m=500, ...), lists the five parcels with marginal coverage, and offers save_geojson to export them for QGIS.

Python use

The tool handlers are plain functions and can be called without MCP:

from urban_mcp.tools.accessibility import ptal_score

print(ptal_score([
    {"stop_id": "s1", "walk_minutes": 4,
     "routes": [{"route_id": "B1", "mode": "bus", "frequency_per_hour": 6},
                {"route_id": "B2", "mode": "bus", "frequency_per_hour": 12}]},
    {"stop_id": "s2", "walk_minutes": 10,
     "routes": [{"route_id": "R1", "mode": "rail", "frequency_per_hour": 4}]},
])["ptal_band"])   # 2

urban_mcp.server.build_server(ServerConfig(...)) returns the configured MCPServer, for embedding or in-process testing with mcp.Client.

Security notes

• No arbitrary code execution. Tools only accept data (GeoJSON, arrays, numbers, enums) validated against JSON schemas and again in the handler; nothing is evaluated or imported from user input, and no tool reads files by path.
• File writes are opt-in and confined. Only save_geojson writes, only when the server was started with --output-dir, only plain file names inside that folder (no paths, no ..), and it never overwrites unless overwrite=true. Note: zero2route3d-sdk creates an empty zero2route3d_cache folder in the system temp directory when it parses a network; nothing else is written there by the routing tools.
• No network by default. Only fetch_osm_street_network goes online, only with --allow-network, with a bounded bbox (about 5 x 5 km) and 12 s timeouts; its cache goes to --output-dir/osm_cache or a temporary folder that is deleted afterwards. The routing tools never fetch elevation online (fetch_online_dem=False).
• Bounded work. Input layers for the quadratic tools are capped (--max-input-features, 4 million matrix cells, 1 500 features for GWR), outputs are truncated, and long computations run in a worker thread so the server stays responsive.
• Errors are tool errors. Invalid input returns an MCP tool result with isError: true and a message that says what to fix; the server does not crash.
• HTTP transport binds to 127.0.0.1 by default and has no authentication; put it behind an authenticating proxy before exposing it.
• Model outputs are screening results. The seismic tool in particular uses uncalibrated design-level mapping (see urban://methods/seismic-screening).

Development

git clone https://github.com/YusufEminoglu/urban_mcp_sdk
cd urban_mcp_sdk
pip install -e ".[dev]"
python -m pytest --cov=urban_mcp     # handler tests + in-process MCP client round trips
python -m ruff check . && python -m ruff format --check src tests
python -m mypy src

Citation

See CITATION.cff. Please also cite the underlying SDKs and the original method papers listed in the urban://methods/* resources.

License

MIT (c) Yusuf Eminoğlu. OpenStreetMap data fetched by the OSM tool is (c) OpenStreetMap contributors, ODbL 1.0.