@invarya/maps-mcp

MCP (Model Context Protocol) server for maps.guru — geocoding, map styles, GIS export, and more for AI assistants.

Setup

Get an API key at maps.guru/dashboard/tokens
Set MAPS_GURU_API_KEY environment variable

Claude Desktop

Add to ~/Library/Application Support/Claude/claude_desktop_config.json:

{
  "mcpServers": {
    "maps-guru": {
      "command": "npx",
      "args": ["-y", "@invarya/maps-mcp"],
      "env": {
        "MAPS_GURU_API_KEY": "mapx_your_api_key_here"
      }
    }
  }
}

Cursor / Windsurf

Add to .cursor/mcp.json or .windsurf/mcp.json:

{
  "mcpServers": {
    "maps-guru": {
      "command": "npx",
      "args": ["-y", "@invarya/maps-mcp"],
      "env": {
        "MAPS_GURU_API_KEY": "mapx_your_api_key_here"
      }
    }
  }
}

Testing with MCP Inspector

MAPS_GURU_API_KEY="mapx_your_key" npx @modelcontextprotocol/inspector npx @invarya/maps-mcp

Opens a web UI at http://localhost:6274 — connect, browse all 15 tools, and run them interactively.

Available Tools (15)

Geocoding

Tool	Description
`geocode`	Forward geocode — address/place name to coordinates
`reverse_geocode`	Reverse geocode — coordinates to address
`autocomplete`	Address autocomplete with partial input
`place_lookup`	Get place details by Pelias ID

GIS Export

Tool	Description
`get_tile_url`	Get tile URL with QGIS-ready connection URI
`get_style_json`	Get full MapLibre GL style JSON
`get_static_map`	Generate static map image (PNG)
`get_dataset_geojson`	Export dataset as GeoJSON

Styles

Tool	Description
`list_styles`	List your map styles
`create_style`	Create a new style from preset
`modify_style_ai`	AI-powered style modification via natural language
`share_style`	Make a style publicly accessible
`brand_style`	Generate a brand-matched map style from a URL

Data & Account

Tool	Description
`list_datasets`	List datasets for a style
`get_usage`	Get current API usage and quotas

Resources

Resource	Description
`style-presets`	Available map style presets
`service-info`	API capabilities and limits

Environment Variables

Variable	Required	Default	Description
`MAPS_GURU_API_KEY`	Yes	—	Your maps.guru API key (`mapx_...`)
`MAPS_GURU_BASE_URL`	No	`https://maps.guru`	API base URL

QGIS Integration

Two MCP servers cooperate through the AI assistant:

User: "Add my city-streets map to QGIS"

Claude:
  1. maps_guru.get_tile_url({ style_slug: "city-streets" })
     -> { qgis_uri: "type=xyz&url=...?key=mapx_xxx&zmax=14" }

  2. qgis.add_raster_layer({ path: qgis_uri, provider: "wms" })
     -> QGIS loads the tile layer

License

MIT