maps.guru
Mcp

Setup

Connect maps.guru MCP using verified setup paths for Claude, ChatGPT, Copilot Studio, local MCP clients, and SDK-based workflows.

Quick install

The fastest way to install is to let an AI agent do it. Humans fat-finger configs.

For humans

Copy this prompt into your LLM agent (Claude Code, Cursor, Codex, OpenCode, etc.) and let it drive the installation:

Install and configure the maps.guru MCP server by following the
instructions here: https://docs.maps.guru/mcp/install.md

The agent will ask you which client you're using, get your API key, write the config, and run a verification prompt.

For LLM agents

Fetch the installation guide and follow the steps:

curl -s https://docs.maps.guru/mcp/install.md

The guide is a short, decision-tree-shaped markdown file optimized for agent consumption. It covers transport selection, API key handling, per-client config paths, and verification.

If you prefer to read through the full human-facing setup manually, continue below.

Prerequisites

Pick the right transport

maps.guru MCP supports two transport modes. Which one you use depends on what your client supports:

MethodURL / CommandBest for
Remotehttps://mcp.maps.guru/mcpClaude custom connectors, ChatGPT custom connectors, xAI API / SDK, Copilot Studio
Localnpx @invarya/maps-mcpClaude Desktop local MCP, Cursor, Windsurf, Cline, OpenCode, Gemini SDK

If you're unsure, remote is the easier option whenever your client supports it — there's nothing to install and authentication happens through a standard OAuth login on maps.guru.

Remote MCP

Use the hosted endpoint whenever your client can connect to a public MCP server over HTTP.

Claude web and desktop custom connectors

Claude supports remote MCP custom connectors across its Pro, Max, Team, and Enterprise plans.

Pro and Max:

  1. Open Customize → Connectors
  2. Click + then Add custom connector
  3. Enter https://mcp.maps.guru/mcp
  4. Leave advanced auth settings at the defaults unless your workspace admin says otherwise
  5. Finish adding the connector
  6. When Claude redirects to maps.guru, sign in and authorize

Team and Enterprise:

  1. An owner opens Organization settings → Connectors
  2. Click Add, choose Custom, then Web
  3. Enter https://mcp.maps.guru/mcp
  4. Once the connector is added, each user goes to Customize → Connectors and clicks Connect

Enable the connector per conversation from the + button in chat.

References:

ChatGPT custom connector

  1. Open Settings → Connectors
  2. If needed, enable Developer mode in advanced connector settings
  3. Add a custom connector
  4. Use https://mcp.maps.guru/mcp as the MCP server URL
  5. Complete the maps.guru authorization flow when ChatGPT redirects you

Custom connectors are available on Plus, Pro, Business, Enterprise, and Edu plans. Some workspace permissions depend on your plan and role.

References:

xAI API / SDK

For Grok-powered tooling, use maps.guru as a remote MCP tool in the xAI Responses API:

curl https://api.x.ai/v1/responses \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $XAI_API_KEY" \
  -d '{
    "model": "grok-4-1-fast-reasoning",
    "input": [
      {
        "role": "user",
        "content": "Geocode Connaught Place in New Delhi"
      }
    ],
    "tools": [
      {
        "type": "mcp",
        "server_url": "https://mcp.maps.guru/mcp",
        "server_label": "maps-guru",
        "authorization": "Bearer eyJ...your_jwt_here"
      }
    ]
  }'

mcp.maps.guru/mcp requires an OAuth 2.1 JWT bearer token — not a mapx_ API key. Long-lived mapx_ keys are accepted on the public maps, tiles, and geocoding APIs (maps.guru/api/v1/*), but the MCP surface is OAuth-only. Get a JWT by completing the OAuth flow at https://maps.guru/.well-known/oauth-authorization-server (most clients do this automatically on first connect).

Reference: xAI: Remote MCP Tools

Microsoft Copilot Studio

This flow is for Copilot Studio agents, not the consumer Copilot chat app.

  1. Open your agent in Copilot Studio
  2. Use the MCP onboarding wizard to connect an existing MCP server
  3. Enter https://mcp.maps.guru/mcp
  4. Add the connected MCP server to the agent's tools
  5. Authenticate when prompted

Copilot Studio currently supports Streamable transport for MCP.

References:

Direct API usage with OpenAI Responses

If you're building your own app against the OpenAI API (instead of ChatGPT's UI), pass maps.guru as a remote MCP tool:

curl https://api.openai.com/v1/responses \
  -H "Authorization: Bearer $OPENAI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gpt-5",
    "input": "Geocode the Eiffel Tower in Paris",
    "tools": [
      {
        "type": "mcp",
        "server_url": "https://mcp.maps.guru/mcp",
        "server_label": "maps-guru",
        "authorization": "Bearer eyJ...your_jwt_here",
        "require_approval": "never"
      }
    ]
  }'

Same OAuth-only rule applies: pass a Better-Auth-issued JWT, not a mapx_ key. ChatGPT's custom-connector UI handles the OAuth dance for you; for direct API usage you'll need to obtain a token via the OAuth 2.1 flow first.

Reference: OpenAI Docs: Connectors and remote MCP servers

Local MCP

Use local mode when your client launches MCP servers as local commands over stdio. Requires Node.js 18+.

Claude Desktop, Cursor, Windsurf, Cline, and OpenCode

Recommended (OAuth 2.1 login): Sign in once with the CLI, then point your client at the server. Credentials are stored in your OS keychain — no secrets in config files.

npx @invarya/maps-mcp auth login

The CLI opens your browser to maps.guru, waits for you to approve the requested scopes, and stores the resulting JWT + refresh token in the keychain. After that, drop this into your client's MCP config:

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

The server reads JWT credentials from the keychain on every launch and auto-refreshes them 60 seconds before expiry. Run npx @invarya/maps-mcp auth status to verify (shows your email address, scopes granted, time to expiry), or auth logout to remove stored credentials and delete the per-machine OAuth client on the server.

Legacy (mapx_ env var): If you can't use the keychain (CI environments, headless servers without libsecret, or you'd rather paste an API key), keep using MAPS_GURU_API_KEY:

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

Both paths stay supported. The CLI checks MAPS_GURU_BEARER_TOKEN env first, then keychain, then MAPS_GURU_API_KEY env, then errors.

Config locations by client:

  • Claude Desktop: ~/Library/Application Support/Claude/claude_desktop_config.json on macOS, %APPDATA%\Claude\claude_desktop_config.json on Windows, ~/.config/Claude/claude_desktop_config.json on Linux
  • Cursor: project .cursor/mcp.json or your global Cursor MCP settings
  • Windsurf: your Windsurf MCP settings file
  • Cline: VS Code Cline MCP settings
  • OpenCode: your OpenCode MCP configuration

Restart the client after saving.

Google Gemini SDK

Google's MCP integration lives in the Gen AI SDK and is marked experimental. Here's the local stdio path in Python:

import asyncio

from google import genai
from mcp import ClientSession, StdioServerParameters
from mcp.client.stdio import stdio_client

client = genai.Client()

server_params = StdioServerParameters(
    command="npx",
    args=["-y", "@invarya/maps-mcp"],
    env={"MAPS_GURU_API_KEY": "mapx_your_api_key_here"},
)

async def run():
    async with stdio_client(server_params) as (read, write):
        async with ClientSession(read, write) as session:
            await session.initialize()
            response = await client.aio.models.generate_content(
                model="gemini-2.5-flash",
                contents="Geocode Bengaluru Palace",
                config=genai.types.GenerateContentConfig(
                    tools=[session],
                    temperature=0,
                ),
            )
            print(response.text)

asyncio.run(run())

Reference: Google Gen AI SDK docs

Clients we don't have a first-party setup path for

A few products that get asked about regularly either don't support third-party MCP servers from their UI or only support MCP through an SDK/API path we've already covered above. If one of these is what you're using, you'll want to fall back to the SDK/API integration path:

  • Google AI Studio UI — Google's published MCP guidance lives in the Gemini SDK docs. Use the Python example above rather than looking for a custom-connector button in AI Studio.
  • Perplexity — Perplexity ships its own MCP server, but there's no public flow for adding third-party MCP servers inside the Perplexity product UI.
  • Grok app / grok.com — xAI's MCP support is through the API and SDK (see above), not a settings flow in the Grok web app.
  • Microsoft Copilot consumer app — Microsoft's MCP docs target Copilot Studio agents, not the consumer Copilot chat app.

Getting your API key

  1. Sign in to maps.guru
  2. Open maps.guru/dashboard/tokens
  3. Copy an existing key or create a new one — your key starts with mapx_

Security: how authentication actually works

How maps.guru MCP authenticates depends on which transport you picked. The two modes have very different trust models.

Remote mode: OAuth 2.1 with PKCE (only auth method)

https://mcp.maps.guru/mcp accepts OAuth 2.1 access tokens, and nothing else. mapx_ API keys are explicitly rejected on the MCP surface. The flow:

  1. The MCP client (Claude, ChatGPT, Copilot Studio, etc.) discovers the OAuth metadata at https://mcp.maps.guru/.well-known/oauth-authorization-server, which redirects to maps.guru's Better-Auth authorization server.
  2. The client opens an authorization URL at maps.guru/api/v1/auth/oauth2/authorize and dynamically registers itself via RFC 7591 if needed.
  3. You sign in to maps.guru, see the consent screen at maps.guru/consent, and approve the requested scopes.
  4. maps.guru issues a short-lived JWT access token (audience https://mcp.maps.guru per RFC 8707) plus a refresh token.
  5. The MCP client sends Authorization: Bearer <jwt> on every /mcp call. mcp-worker verifies the signature against maps.guru/api/v1/auth/jwks on the edge.

You can review and revoke any granted client at maps.guru/dashboard/settings/connected-apps. Revoking a consent invalidates that client's refresh token immediately and forces a fresh OAuth flow on the next request. You never have to rotate a mapx_ key to lock out a misbehaving MCP client.

Why no mapx_ on the MCP surface? mapx_ keys are long-lived bearers — possession equals access. When a key leaks (logs, screenshots, shared configs, an LLM provider's infrastructure), the attacker fully impersonates you within that key's scopes. JWTs solve this with three properties mapx_ can't: short lifetime, per-client binding, and per-grant revocability via the dashboard.

Local mode: OAuth 2.1 login (recommended) or bearer token

stdio MCP runs locally on your machine and authenticates two ways:

OAuth 2.1 login (recommended): Run npx @invarya/maps-mcp auth login once. The CLI spins up an ephemeral localhost listener, opens your browser to the maps.guru consent screen, and waits for the authorization-code redirect. You approve the requested scopes, the browser redirects to http://127.0.0.1:<random-port>/callback, and the CLI exchanges the code for a short-lived JWT (1 hour) plus a refresh token. Both land in your OS keychain — Keychain on macOS, Credential Manager on Windows, libsecret on Linux. The MCP server reads the JWT on every launch and refreshes it automatically 60 seconds before expiry. Your auth status shows the email address from the token (no raw ULIDs). Same UX you already know from gh auth login, aws sso login, and doctl auth init.

If the keychain is unavailable (headless Linux without libsecret, etc.), the CLI falls back to ~/.config/maps-guru/credentials.json with chmod 0600 and prints a warning.

Legacy bearer token via env var: If you can't or won't use the keychain — CI environments, ephemeral containers, or just preference — set MAPS_GURU_API_KEY to a mapx_ key. The server picks it up and sends it as a Bearer token to maps.guru/api/v1/*. This path stays fully supported for backwards compatibility.

How the CLI does OAuth without a long-lived server: every time you run auth login, the CLI binds to an ephemeral loopback port (http://127.0.0.1:0/callback) and sets that exact URL as the redirect_uri on the authorization request. Your browser follows the redirect back to that listener, which receives the code, completes the PKCE (RFC 7636) exchange, then shuts down. This is the OAuth 2.1 native-app pattern described in RFC 8252 §7.3 — the same flow gcloud auth login, aws sso login, and every modern CLI uses.

Manage active CLI installs at maps.guru/dashboard/settings/devices. Each auth login on a new machine shows up as its own row; revoking a device kills that machine's refresh token immediately and forces a fresh auth login on the next request.

If you stick with the mapx_ env-var path, treat the key like a password:

  • Don't commit keys to source control, chat transcripts, or shared docs.
  • Don't paste keys into MCP clients you don't trust or haven't vetted.
  • If a key might have leaked, rotate it at maps.guru/dashboard/tokens. All existing MCP configs using that key stop working until you update them — which is the point.
  • Create a dedicated key per machine or per client if you want tighter blast radius. That way you can revoke one without disturbing the others.

mapx_ keys remain fully supported — and recommended — for the public maps, tiles, and geocoding APIs (maps.guru/api/v1/styles/public/*?key=…, embed URLs, MapTiler-style integrations). The MCP-surface deprecation is scoped: it does not affect any other product surface.

Scope your keys

API keys on maps.guru are scoped. When creating a key specifically for MCP, you can mint one with only the scopes the MCP tools actually need and skip billing or admin scopes entirely. That way even if the key leaks, the damage is limited to what that key could already do — and you can revoke it without touching anything else.

Verifying the setup

After connecting, try:

"What maps.guru tools do you have?"

Then:

"Geocode the Eiffel Tower in Paris"

If the assistant lists tools and returns coordinates, you're good.

Testing with MCP Inspector

For local debugging:

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

This opens the MCP Inspector UI — you can browse tools and invoke them manually to see raw responses.

Next steps

Overview

Learn how the Model Context Protocol (MCP) connects maps.guru to AI assistants and GIS tools.

Available Tools

Complete reference for all 15 MCP tools provided by the maps.guru MCP server.

Copyright © 2026