mapport

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

Tool	Input	What it returns
maps_geocode	address (string, required)	Matching locations with coordinates, formatted address, and place ID.
maps_reverse_geocode	latitude (number, required), longitude (number, required)	The nearest address for the coordinates, with its components.
maps_search_places	query (string, required), location (object, optional), radius (number, optional)	Places matching the query, with names, addresses, and locations.
maps_place_details	place_id (string, required)	Full details for one place: contact info, rating, reviews, and opening hours.
maps_distance_matrix	origins (string[], required), destinations (string[], required), mode (string, optional)	A matrix of distances and travel durations.
maps_elevation	locations (array of {latitude, longitude}, required)	Elevation in metres for each location.
maps_directions	origin (string, required), destination (string, required), mode (string, optional)	Routes with legs, steps, distance, and duration.

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.