Skip to content
devsanthoshmkPublic

About

Google Maps for AI agents, no API key needed

Topics

Resources

Stars

1 star

Watchers

0 watching

Forks

Latest commit

 

History

59 Commits

Folders and files

Repository files navigation

gmaps-mcp

Google Maps MCP server for AI agents and LLM applications.

Python 3.10+ License: MIT

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.

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.

Parameter Type Default Description
term string required Search query or business category such as "coffee shops" or "dentists"
location string required City, neighborhood, or landmark such as "Paris", "Chicago", or "Chennai"
limit integer null Maximum number of results to return
grid boolean false Enable geospatial grid tiling for large area coverage
country string "in" ISO 3166-1 alpha-2 country code such as "us", "fr", or "in"
language string "en" Response language code
result_delivery "inline" | "resource" "inline" Delivery mode. Use "resource" to prevent large result sets from filling the context window

get_place_details

Fetches structured details for a specific place.

Parameter Type Default Description
place string required Google Place ID (e.g. "ChIJ...") or exact business name
country string "in" ISO 3166-1 alpha-2 country code
language string "en" Response language code

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.

About

Google Maps for AI agents, no API key needed

Topics

Resources

Stars

1 star

Watchers

0 watching

Forks

Releases

Packages

Contributors

Languages