# mapsi-mcp

MCP server for [Mapsi](https://mapsi.dev) — 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](https://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):
```json
{
  "mcpServers": {
    "mapsi": {
      "command": "npx",
      "args": ["-y", "mapsi-mcp"],
      "env": { "MAPSI_API_KEY": "msk_your_key_here" }
    }
  }
}
```

### Cursor
Add to `~/.cursor/mcp.json`:
```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:
```json
{
  "mapsi": {
    "command": "npx",
    "args": ["-y", "mapsi-mcp"],
    "env": { "MAPSI_API_KEY": "msk_your_key_here" }
  }
}
```

### Zed
Add to your Zed settings under `"context_servers"`:
```json
{
  "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.
```

---

## Pricing

| Plan | Calls/day | Batch size |
|------|-----------|------------|
| Free | 1,000 | 10 |
| Growth | 50,000 | 5,000 |
| Business | Unlimited | 30,000 |

Full pricing at [mapsi.dev/pricing](https://mapsi.dev/pricing)

---

## Links

- **Website:** [mapsi.dev](https://mapsi.dev)
- **API docs:** [mapsi.dev/docs](https://mapsi.dev/docs)
- **AI prompts:** [mapsi.dev/prompts-for-ai](https://mapsi.dev/prompts-for-ai)
- **npm:** [npmjs.com/package/mapsi-mcp](https://npmjs.com/package/mapsi-mcp)
- **GitHub:** [github.com/algolayer/mapsi-mcp](https://github.com/algolayer/mapsi-mcp)
- **Support:** support@mapsi.dev

---

## License

MIT — [algolayer.com](https://algolayer.com)