GeoGridAPI MCP server

Ask your AI assistant where a business ranks on Google Maps, block by block.

This MCP server gives Claude, Cursor, VS Code, Windsurf and any MCP client the GeoGridAPI tools: it measures a Google Business Profile for a keyword on every point of a grid around it (a local SEO "geo-grid"), then returns the rank map as an image, the competitors ranking ahead and the change since the last measure.

"Run a 7×7 grid for Joe's Pizza in New York on pizza, then tell me who beats them in the north-east."

It runs locally over stdio and relays every call to the hosted server at https://api.geogridapi.io/mcp, so tools stay in sync with the API.

Quick start

1. Create an account on geogridapi.io: 500 free credits, no card.
2. Create an API key in the console. gga_test_ keys are free and return sample grids; gga_live_ keys measure real grids (1 credit = 1 grid point).
3. Add the server to your client (Node.js 20 or later):

Claude Desktop (claude_desktop_config.json), Cursor (.cursor/mcp.json), Windsurf, Cline:

{
  "mcpServers": {
    "geogridapi": {
      "command": "npx",
      "args": ["-y", "geogridapi-mcp"],
      "env": { "GEOGRIDAPI_API_KEY": "gga_live_…" }
    }
  }
}

Claude Code:

claude mcp add geogridapi --env GEOGRIDAPI_API_KEY=gga_live_… -- npx -y geogridapi-mcp

VS Code (.vscode/mcp.json):

{
  "servers": {
    "geogridapi": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "geogridapi-mcp"],
      "env": { "GEOGRIDAPI_API_KEY": "gga_live_…" }
    }
  }
}

Docker:

docker build -t geogridapi-mcp https://github.com/geogridapi/geogridapi-mcp.git
docker run -i --rm -e GEOGRIDAPI_API_KEY=gga_live_… geogridapi-mcp

Your client supports remote servers? You can skip this package and connect straight to https://api.geogridapi.io/mcp, with OAuth (Claude, ChatGPT) or an Authorization: Bearer header. See the MCP documentation.

Tools

Tool	What it does	Cost
find_business	Finds a Google Business Profile by name and city, returns its place_id.	Free
estimate_grid	Exact points and credits of a grid before running it.	Free
run_grid	Measures a listing for a keyword on a grid: square 3×3, 5×5, 7×7 or 9×9, or circle, diamond, hexagon, cross, ellipse, rectangle. Returns the rank map image, average rank, top 3 coverage and competitors ahead.	1 credit per point
run_grids / get_batch	Up to 50 grids in one call: one listing with several keywords, or several listings with one keyword.	1 credit per point
get_grid	A grid with its rank matrix, image, competitors and change since the previous one.	Free
list_grids	Past grids, filtered by listing or keyword.	Free
get_history	Ranking trend of the same map over time.	Free
schedule_grid, list_schedules, update_schedule, delete_schedule	Reruns a grid every week or every month.	1 credit per point per run
get_balance	Credits left.	Free

Six prompts come with it: local visibility audit, who ranks ahead, several keywords, ranking trend, track my listing and client report.

Ranks are positions in the Google Maps results at each grid point: lower is better, null means not in the top 20.

Configuration

Variable	Default
GEOGRIDAPI_API_KEY	none	Required for tool calls. Without it the server still lists its tools.
GEOGRIDAPI_MCP_URL	https://api.geogridapi.io/mcp	Hosted server to relay to.

Development

npm install
npm test                                        # unit tests, no network
GEOGRIDAPI_API_KEY=gga_test_… npm run smoke     # end-to-end over stdio, free
GEOGRIDAPI_API_KEY=gga_test_… npm run sync-catalog  # refresh the offline tool catalog

Related

• local-rank-heatmap: one command, one Google Maps rank heatmap.
• n8n-nodes-geogridapi: the GeoGridAPI node for n8n.
• API documentation and pricing.

License

MIT © Localnord, LLC (GeoGridAPI)