mapport

mapport turns plain questions about places into answers from the Google Maps Platform: an address becomes coordinates, coordinates become an address, a text query becomes a list of places, and any two points become a distance, a duration, or a step-by-step route. It also reports how high a point sits above sea level. One binary serves both a command-line interface for scripts and a stdio MCP server for agents, and both faces share the same request logic.

A Google Maps Platform API key is required. Put it in the GOOGLE_MAPS_API_KEY environment variable; it is sent to Google as the key query parameter on every request and never appears in output. When the variable is missing, every call fails with an error that names it, before any request is made.

Install

npx @reneturcios/mapport geocode "1600 Amphitheatre Parkway"

Or run the container image:

docker run -i -e GOOGLE_MAPS_API_KEY ghcr.io/cloudcorprecords/mapport

The container defaults to the MCP server (see below). Pass CLI arguments to use it as a CLI instead.

CLI

export GOOGLE_MAPS_API_KEY="your API key"

mapport geocode "1600 Amphitheatre Parkway, Mountain View"
mapport reverse 37.422 -122.084
mapport search "coffee near the ferry building" --lat 37.7955 --lng -122.3937 --radius 1500
mapport details ChIJ2eUgeAK6j4ARbn5u_wAGqWA
mapport distance "San Francisco" "Oakland" --to "Berkeley" --mode driving
mapport elevation 37.422,-122.084 40.0,-70.0
mapport directions "San Francisco" "San Jose" --mode transit

mapport --version

Each command prints the upstream JSON payload. Exit codes: 0 on success, 1 when a call fails (including a missing GOOGLE_MAPS_API_KEY or an API error), 2 for usage errors.

MCP server

One bin serves both faces. The mcp subcommand starts a stdio MCP server:

npx -y @reneturcios/mapport mcp

MCP client configuration:

{
  "mcpServers": {
    "mapport": {
      "command": "npx",
      "args": ["-y", "@reneturcios/mapport", "mcp"],
      "env": { "GOOGLE_MAPS_API_KEY": "your API key" }
    }
  }
}

Tools

Google reports most API failures inside an HTTP 200 payload, in a top-level status field. mapport surfaces any status other than OK or ZERO_RESULTS as a tool error naming the status and Google's own message; ZERO_RESULTS is returned as an honest empty answer.

Development

npm install
npm run build   # tsc -> dist/
npm test        # node test runner over test/*.test.ts, no network (fake fetch fixtures)
npm run dev     # run the CLI from source via tsx

License

MIT — see LICENSE.