Overview
The Model Context Protocol (MCP) is a standard interface for letting AI clients call external tools. maps.guru speaks MCP — geocoding, map styles, static images, GIS exports, usage checks, and dataset tools are all exposed through a single server.
You can connect in two ways:
- Remote:
https://mcp.maps.guru/mcp— for clients that support HTTP or Streamable HTTP MCP - Local:
npx @invarya/maps-mcp— for clients that launch MCP servers as local stdio processes
What can you do?
With maps.guru MCP connected, your AI assistant can:
- Geocode addresses — "What are the coordinates for 1600 Pennsylvania Ave?"
- Generate static maps — "Create a 1200x800 map of downtown Tokyo at zoom 14"
- Manage map styles — "List my styles and share the dark theme publicly"
- Export for GIS — "Give me a QGIS-ready tile URL for my city-streets style"
- Check usage — "How many API calls have I used this month?"
How it works
Remote (HTTP / Streamable HTTP)
AI client ──► https://mcp.maps.guru/mcp ──► maps.guru REST API /api/v1/*
Local (stdio)
AI client ──► @invarya/maps-mcp (your machine) ──► maps.guru REST API /api/v1/*
Remote mode is the right fit when your client supports custom connectors or remote MCP servers. Auth goes through an OAuth 2.1 + PKCE login flow on maps.guru — the client never sees your API key directly.
Local mode is the right fit when your client expects to start a local command. You drop your mapx_ API key into the config and the server runs on your machine.
Which clients work
| Client | Supported flow | maps.guru mode |
|---|---|---|
| Claude (web / desktop) | Custom connectors with remote MCP | Remote |
| ChatGPT | Custom connectors in ChatGPT and remote MCP in the Responses API | Remote |
| Claude Desktop (local) | Local stdio MCP config file | Local |
| Cursor / Windsurf / Cline / OpenCode | Local stdio MCP config | Local |
| Google Gemini SDK | MCP integration in the Gemini SDK | Local |
| xAI API / SDK | Remote MCP tools | Remote |
| Microsoft Copilot Studio | Connect an existing MCP server to an agent | Remote |
Clients we don't have a first-party setup path for (yet)
A few popular products ship MCP support that either doesn't extend to third-party servers yet or lives in docs we'd rather not guess at. If you use one of these, stick to the SDK/API path or reach out and we'll take another look:
- Google AI Studio UI — Google's MCP docs today focus on the Gemini SDK, not an AI Studio custom connector flow.
- Perplexity app — Perplexity publishes its own MCP server, but there's no public flow for adding arbitrary third-party MCP servers inside the Perplexity UI.
- Grok app / grok.com UI — xAI documents remote MCP through its API and SDK, not a Grok settings flow.
- Microsoft Copilot consumer app — Microsoft's MCP docs target Copilot Studio agents, not the consumer Copilot chat app.
What you get
A thin wrapper around the API you already use
The MCP server is a lightweight client over maps.guru/api/v1/*. Your own API key (or OAuth session, for remote) still controls quota, scopes, and billing — there's no separate MCP account or billing surface.
GIS tool interoperability
Tool responses return QGIS-ready URIs, full MapLibre style.json, and GeoJSON. You can plug a second MCP server (like one that controls QGIS) into the same conversation and let the assistant coordinate both.
15 tools and 2 resources
Geocoding, reverse geocoding, style management, static maps, datasets, usage, and more. Resources cover style preset discovery and API capability info.
Official references
- Anthropic: Connect your tools to Claude with custom connectors
- OpenAI: Connectors in ChatGPT
- OpenAI: Remote MCP in the Responses API
- Google Gen AI SDK: MCP support
- xAI: Remote MCP
- Microsoft Copilot Studio: Connect to an existing MCP server
Next steps
- Setup — installation for each supported client
- Available Tools — full tool reference
- GIS Integration — QGIS and MapLibre workflows