gmaps-mcp

Google Maps MCP server for AI agents and LLM applications.

Purpose

gmaps-mcp is an open-source Google Maps MCP server and command line interface built on the Model Context Protocol. It provides an AI agent maps tool that requires no API key, billing account, or browser automation setup.

AI assistants in Claude Desktop, Cursor, Cline, Windsurf, Zed, and OpenCode connect to this Model Context Protocol Google Maps server to search local businesses, inspect reviews and star ratings, find phone numbers and websites, and retrieve geographic coordinates. The tool runs locally through standard input/output (stdio) or across networks through Streamable HTTP.

Related MCP server: Google Maps MCP Server

Architecture

The system has four core layers:

1. Protocol layer. Built with the official MCP Python SDK (mcp.server.mcpserver.MCPServer). Exposes tools and resources over stdio or Streamable HTTP transports. Server logging writes strictly to stderr so stdout remains clean JSON-RPC for MCP clients.

2. Scraper engine. Built on aiohttp and phonenumbers. The engine queries Google Maps endpoints directly with asynchronous HTTP requests, parses raw response payloads, extracts place records, and normalizes phone numbers into E.164 format. It runs without Playwright, Puppeteer, or browser binaries.

3. Geospatial grid tiling. When searching broad areas or entire cities, the grid crawler calculates the geographic bounding box and subdivides the region into smaller viewport tiles. This bypasses the standard 20-result pagination cap of Google Maps and collects hundreds of places per query.

4. Storage and delivery layer. When result sets exceed normal prompt budgets, the server stores full result objects in memory and returns an MCP resource URI (gmaps://results/{resource_id}). Clients fetch the complete payload through the MCP resource interface, preventing context window exhaustion.

Setup

Requirements

• Python 3.10 or higher

• uv package manager (recommended) or pip

Install and run with uvx

Run the server directly without cloning:

uvx --from git+https://github.com/devsanthoshmk/gmaps-mcp.git gmaps-mcp serve

Install from source

Clone the repository and install dependencies with uv:

git clone https://github.com/devsanthoshmk/gmaps-mcp.git
cd gmaps-mcp
uv sync

Usage

Run as an MCP server

Start the server using stdio transport (default):

uv run gmaps-mcp serve

Start the server using Streamable HTTP transport:

uv run gmaps-mcp serve --transport streamable-http --host 127.0.0.1 --port 8000

Run via command line

Search places

Search for places and display a formatted table:

uv run gmaps-mcp search "dentists" "Chicago" --limit 10 --country us --format table

Search across an entire city using geospatial grid tiling:

uv run gmaps-mcp search "bakeries" "Paris" --country fr --grid --format table

Export search results to CSV or JSON:

uv run gmaps-mcp search "pharmacies" "Chennai" --grid --country in --output pharmacies.csv
uv run gmaps-mcp search "coffee shops" "Seattle" --country us --output coffee.json

Get place details

Look up details by Google Place ID:

uv run gmaps-mcp details "ChIJ7xiFY1VmUjoR2IuH0fYWMlk" --format table

Look up details by name and export to CSV:

uv run gmaps-mcp details "Eiffel Tower Paris" --country fr --output eiffel.csv

Configuration

Claude Desktop

To configure Claude Desktop MCP Maps integration, add gmaps-mcp to claude_desktop_config.json:

{
  "mcpServers": {
    "google-maps": {
      "command": "uvx",
      "args": [
        "--from",
        "git+https://github.com/devsanthoshmk/gmaps-mcp.git",
        "gmaps-mcp",
        "serve"
      ]
    }
  }
}

Config file paths by platform:

• macOS: ~/Library/Application Support/Claude/claude_desktop_config.json

• Windows: %APPDATA%\Claude\claude_desktop_config.json

• Linux: ~/.config/Claude/claude_desktop_config.json

Cursor

Add to .cursor/mcp.json or your global Cursor MCP configuration:

{
  "mcpServers": {
    "google-maps": {
      "command": "uvx",
      "args": [
        "--from",
        "git+https://github.com/devsanthoshmk/gmaps-mcp.git",
        "gmaps-mcp",
        "serve"
      ]
    }
  }
}

Windsurf, Cline, and Zed

Add to your client MCP configuration:

{
  "mcpServers": {
    "google-maps": {
      "command": "uvx",
      "args": [
        "--from",
        "git+https://github.com/devsanthoshmk/gmaps-mcp.git",
        "gmaps-mcp",
        "serve"
      ]
    }
  }
}

Install with mcp-add

Add the server using the mcp-add utility:

npx mcp-add -n google-maps -t stdio -c "uvx --from git+https://github.com/devsanthoshmk/gmaps-mcp.git gmaps-mcp serve"

Local development configuration

Point an MCP client to a local repository checkout:

{
  "mcpServers": {
    "google-maps": {
      "command": "uv",
      "args": [
        "run",
        "--directory",
        "/absolute/path/to/gmaps-mcp",
        "gmaps-mcp",
        "serve"
      ]
    }
  }
}

Available tools

The server registers two MCP tools:

search_google_maps

Searches Google Maps for businesses, places, and points of interest.

get_place_details

Fetches structured details for a specific place.

Output schema

Places return structured JSON matching this schema:

{
  "place_id": "ChIJ7xiFY1VmUjoR2IuH0fYWMlk",
  "name": "New Chennai Pharmacy",
  "category": "Pharmacy",
  "address": "No. 33, Sarojini Street, T.Nagar, Chennai, Tamil Nadu 600017",
  "phone": "091500 97960",
  "international_phone": "+91 91500 97960",
  "website": "https://example.com",
  "domain": "example.com",
  "latitude": 13.0371485,
  "longitude": 80.2319365,
  "rating": 4.7,
  "review_count": 25,
  "google_maps_url": "https://www.google.com/maps/place/?q=place_id:ChIJ7xiFY1VmUjoR2IuH0fYWMlk"
}

Development

Run the test suite:

uv run --extra dev pytest

License

MIT license in LICENSE.