🗺️ gmaps-mcp

A Google Maps scraper server and CLI for AI agents and terminal use. No API key required.

---

⚡ Key Features

• No API key — scrapes Google Maps directly via aiohttp
• Search businesses by query with pagination and geo-grid tiling
• Place details — full profile by Place ID or name (phone, address, rating, coordinates)
• Grid mode — tiles an entire city/region into sub-viewports to collect thousands of results
• MCP + CLI — same engine, two interfaces

---

🚀 Quickstart

Add to AI Agents (Claude Desktop, Cursor, Windsurf, Cline, Zed, etc.)

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

Or Run via CLI

# Direct run without cloning
uvx --from git+https://github.com/devsanthoshmk/gmaps-mcp.git gmaps-mcp search "bakeries" "Paris" --country fr --limit 10

# Or clone and run locally
git clone https://github.com/devsanthoshmk/gmaps-mcp.git
cd gmaps-mcp
uv run gmaps-mcp search "bakeries" "Paris" --country fr --limit 10

---

💻 CLI

Search

uv run gmaps-mcp search "dentists" "Chicago" --limit 10 --country us --format table
uv run gmaps-mcp search "bakeries" "Paris" --country fr --grid --format table
uv run gmaps-mcp search "pharmacies" "Chennai" --grid --country in --output pharmacies.csv

Place Details

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

Start MCP Server

uv run gmaps-mcp serve                                                         # stdio (default)
uv run gmaps-mcp serve --transport streamable-http --host 0.0.0.0 --port 8000  # HTTP

---

🔌 MCP Client Config (Manual)

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

Local dev:

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

---

🧩 MCP Tools

search_google_maps

Parameter	Type	Default	Description
term	string	required	Search term / business category (e.g. "coffee shops", "dentists")
location	string	required	Target location / city (e.g. "Paris", "Chicago", "Chennai")
limit	integer	null	Max results
grid	boolean	false	Enable geo-grid tiling for large area coverage
country	string	"in"	ISO country code ("us", "fr", "jp")
language	string	"en"	Response language
result_delivery	"inline" | "resource"	"inline"	"resource" avoids context bloat for large result sets

get_place_details

Parameter	Type	Default	Description
place	string	required	Place ID ("ChIJ...") or business name
country	string	"in"	ISO country code
language	string	"en"	Response language

---

📦 Output 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",
  "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"
}

---

📄 License

MIT — see LICENSE.