MCP 服务器

mapsi-mcp

Geospatial API tools for AI agents — geocoding, reverse geocoding, routing, isochrone, distance matrix, static maps, H3 hexagons, elevation, GPS map-matching, point-in-polygon, address normalisation, timezone lookup, and batch geocoding. Built on OpenStreetMap infrastructure. Cost-effective alternative to Google Maps API.

README

mapsi-mcp

MCP server for Mapsi — 18 geospatial tools for AI coding assistants. Connect Claude Code, Cursor, Windsurf, or any MCP-compatible IDE directly to Mapsi APIs.

OpenStreetMap-based · Self-hosted infrastructure · No Google Maps vendor lock-in

Quick Start

1. Get your API key at mapsi.dev/console/api-keys (free tier: 1,000 calls/day, no credit card)

2. Add the config to your IDE:

Claude Code / Claude Desktop

Add to ~/.claude.json (or .mcp.json in your project root):

{
  "mcpServers": {
    "mapsi": {
      "command": "npx",
      "args": ["-y", "mapsi-mcp"],
      "env": { "MAPSI_API_KEY": "msk_your_key_here" }
    }
  }
}

Cursor

Add to ~/.cursor/mcp.json:

{
  "mcpServers": {
    "mapsi": {
      "command": "npx",
      "args": ["-y", "mapsi-mcp"],
      "env": { "MAPSI_API_KEY": "msk_your_key_here" }
    }
  }
}

Windsurf

Add to ~/.codeium/windsurf/mcp_config.json — same JSON format as Cursor above.

VS Code + Cline

Open Cline settings → MCP Servers → Add server → paste:

{
  "mapsi": {
    "command": "npx",
    "args": ["-y", "mapsi-mcp"],
    "env": { "MAPSI_API_KEY": "msk_your_key_here" }
  }
}

Zed

Add to your Zed settings under "context_servers":

{
  "mapsi-mcp": {
    "command": { "path": "npx", "args": ["-y", "mapsi-mcp"] },
    "env": { "MAPSI_API_KEY": "msk_your_key_here" }
  }
}

3. Restart your IDE — then ask your AI in plain English.

What You Can Ask Your AI

Geocode all addresses in my CSV and add lat/lon columns
Build an address autocomplete input for this React form using Mapsi
Draw a 20-minute drive isochrone from our warehouse at this coordinate
Find the 5 nearest hospitals to this coordinate
Migrate this Google Maps geocoding call to Mapsi
Add a MapLibre map with Mapsi light tiles and drop markers from this array
Calculate a distance matrix between 10 warehouses and 50 delivery stops
Snap this GPS trace to the road network and calculate total distance

Available Tools (18)

Geocoding

Tool	Description
`geocode`	Address or place name → lat/lon. Returns confidence score (0–1); treat scores below 0.6 as ambiguous.
`reverse_geocode`	lat/lon → formatted address, street, city, postcode, country.
`autocomplete`	Real-time address suggestions as user types (min 2 chars). For UI input fields.
`normalize_address`	Standardize messy/inconsistent addresses. Returns structured fields + coordinates.
`timezone`	IANA timezone name + UTC offset + DST status for any coordinate.
`elevation`	Altitude in metres for any coordinate (~30m resolution globally).

Routing

Tool	Description
`route`	Turn-by-turn directions. Modes: auto, truck, bicycle, pedestrian, motor_scooter.
`isochrone`	Reachability polygon within N minutes or N metres. Returns GeoJSON for MapLibre/Leaflet.
`matrix`	Travel time + distance matrix for up to 50×50 origin-destination pairs in one call.
`map_match`	Snap a GPS trace to the road network. Coordinates are [lon, lat] order (GeoJSON).
`nearest_road`	Find nearest routable road point. Call this if `route` returns "no route found".

Places

Tool	Description
`places_search`	Find nearby POIs by category (restaurant, hospital, pharmacy, ATM…). Returns name, coords, categories.

Spatial

Tool	Description
`point_in_polygon`	Admin hierarchy for a coordinate: country, region, city, neighbourhood.
`h3_index`	Convert coordinate to H3 hexagonal grid cell at resolution 0–15.

Batch

Tool	Description
`batch_geocode`	Geocode up to 30,000 addresses in a single call. Never loop `geocode` for bulk data.
`batch_reverse_geocode`	Reverse geocode multiple coordinates in one call.

Tiles

Tool	Description
`get_tile_style_url`	MapLibre GL style URL. Styles: light, dark, streets, topo, grayscale, black, white, liberty.
`get_static_map_url`	Static PNG map URL for use in `<img>` tags, emails, and PDFs.

Auth

API calls: X-API-Key header (handled automatically by the MCP server)
Tile URLs: ?key= query param (browser-safe; returned by get_tile_style_url)

Common Patterns for Agents

Geocode once, reuse the result:

Don't re-geocode the same address twice within a session. Cache the lat/lon and pass it directly to route, isochrone, and places_search.

Bulk data → batch tools:

For more than 1 address or coordinate pair, always use batch_geocode / batch_reverse_geocode.

Route fails → nearest_road first:

If route returns an error near the origin or destination, call nearest_road to snap the point to a routable road, then retry route with the snapped coordinates.

Isochrone — time vs distance:

Use contours_minutes for time-based reachability (delivery ETAs, commute zones).
Use contours_meters for fixed-radius circles on the road network.
Provide only one, not both.