@invarya/maps-mcp

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

Setup

1. Get an API key at maps.guru/dashboard/tokens
2. 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