@goggleplaces/mcp-server

The official Model Context Protocol server for the Goggle Places API. It exposes Goggle Places' query endpoints as MCP tools so any MCP-capable AI agent — Claude Code, Claude Desktop, or any other MCP host — can search places, find nearby amenities, get directions, look up addresses, and share routes directly from a conversation.

It is a small Node stdio server with no browser dependencies.

Tools

| Tool | What it does | | --- | --- | | search | Predictive place and postcode search across Great Britain (q, optional lat/lng/limit). | | nearby | Nearby points of interest and amenities around a coordinate (lat, lng, optional categories/radius/limit). | | directions | Route between two points with distance and travel time (from, to, optional mode). | | address | Address lookup by postcode, street or town (q). | | share_route | Build shareable links and a GPX file for a route (origin, destination, optional mode/waypoints/name). | | create_api_key | Self-provision a free-tier API key with no signup. Returns a key to use with the other tools, plus a claim_url for your user. | | get_claim_link | Get a fresh claim link for a self-provisioned key (if the first was lost or expired). | | credit_status | Prepaid credit balance, whether the key is activated, and trial usage. | | buy_credits | How to buy a £5 / £20 / £50 credit pack over MPP (Machine Payments Protocol). |

Every tool that returns map or place data includes the required data attribution line in its result.

Install

The server is published to npm, so there's nothing to clone — the config snippets below run it with npx @goggleplaces/mcp-server, which fetches and caches it automatically.

To hack on it locally instead, from the monorepo root:

npm install
npm run build -w @goggleplaces/mcp-server

This produces the runnable server at packages/mcp-server/dist/index.js; use node /abs/path/to/packages/mcp-server/dist/index.js in place of the npx command.

Configuration

The server reads two environment variables:

• GOGGLE_PLACES_API_KEY — your API key. Optional: you can also mint a free-tier key at runtime with the create_api_key tool, or pass api_key to any tool call.
• GOGGLE_PLACES_API_BASE — API base URL. Defaults to https://api.goggleplaces.com.

Claude Code

claude mcp add goggleplaces \
  --env GOGGLE_PLACES_API_KEY=gk_live_your_key_here \
  --env GOGGLE_PLACES_API_BASE=https://api.goggleplaces.com \
  -- npx -y @goggleplaces/mcp-server

Claude Desktop

Add an entry under mcpServers in claude_desktop_config.json:

{
  "mcpServers": {
    "goggleplaces": {
      "command": "npx",
      "args": ["-y", "@goggleplaces/mcp-server"],
      "env": {
        "GOGGLE_PLACES_API_KEY": "gk_live_your_key_here",
        "GOGGLE_PLACES_API_BASE": "https://api.goggleplaces.com"
      }
    }
  }
}

Restart Claude Desktop after saving.

Generic MCP host

Launch the server over stdio with the same command and environment:

GOGGLE_PLACES_API_KEY=gk_live_your_key_here \
GOGGLE_PLACES_API_BASE=https://api.goggleplaces.com \
npx -y @goggleplaces/mcp-server

Self-provisioning a key

You do not need to sign up to get started. Call the create_api_key tool and the server returns a free-tier key your agent can use immediately — set it as GOGGLE_PLACES_API_KEY or pass it as the api_key argument to subsequent tool calls.

Trial, activation and going further

A self-provisioned key starts as a trial with a small number of calls — enough to prove your integration works. Activate it to unlock the full free monthly allowance, either way:

• Prepaid credit (fully agent-driven). Call buy_credits for a £5, £20 or £50 pack. It returns the exact command to pay over MPP, e.g. with Stripe's Link CLI — your user approves the spend in their Stripe Onelink wallet. £5 or more activates the key, and credit is only spent on usage beyond the free allowance.
• Claim + card. Hand your user the claim_url from create_api_key. They sign in at app.goggleplaces.com, claim the key into their organisation and add a card. The same key keeps working, with pay-as-you-go beyond the free allowance, and any unspent credit moves across with it.

Claim links are single-use and expire after 30 days (get_claim_link issues a fresh one). credit_status shows the balance, activation and trial usage at any time.

Releasing

Publishing is automated by the .github/workflows/publish-mcp-server.yml GitHub Action, which runs on a version tag and publishes to npm. Build provenance (an OIDC-signed attestation linking the package to the exact commit that built it) is ready to switch on by adding --provenance to the publish step — once this repo is public, which npm provenance requires.

To cut a release:

npm version patch -w @goggleplaces/mcp-server   # bump 0.1.0 -> 0.1.1 (or minor/major)
git commit -am "mcp-server: release vX.Y.Z"
git tag mcp-server-vX.Y.Z                        # tag pattern the workflow listens for
git push && git push --tags

The workflow builds and runs npm publish --access public. One-time setup: add an npm granular access token (org @goggleplaces, publish permission) as the NPM_TOKEN repository secret — or configure npm Trusted Publishing for this package on npmjs.com to publish tokenlessly (see the workflow comments).

Attribution

Results include: Data: © OpenStreetMap contributors (ODbL); Contains OS data © Crown copyright and database right (OGL).