nextbillion-mcp

MCP server exposing NextBillion.ai location APIs as tools for AI agents: geocoding, place search, routing, distance matrices, isochrones, and static maps.

Implements the MCP 2026-07-28 specification (stateless core) via the official TypeScript SDK v2; older-protocol clients are served through the SDK's built-in legacy negotiation.

Quick start

Get an API key at console.nextbillion.ai and export it as NBAI_API_KEY in your shell profile.

Claude Code plugin (this repository doubles as a plugin marketplace):

claude plugin marketplace add nextbillion-ai/nextbillion-mcp
claude plugin install nextbillion-mcp@nextbillion

Any MCP client — snippets for Claude Code, Cursor, and Codex are in distributions/manual/README.md. The short version:

NBAI_API_KEY=<your key> npx -y nextbillion-mcp

Tools

Tool	NextBillion API
autocomplete	Autocomplete (prefix address completion)
autosuggest	Autosuggest (typo-tolerant suggestions)
directions	Directions (fast + flexible)
distance_matrix	Distance Matrix (fast + flexible, synchronous)
geocode_batch	Batch Geocode (up to 100 queries per call)
geocode_forward	Forward Geocode
geocode_reverse	Reverse Geocode
geocode_structured	Structured Geocode
isochrone	Isochrone
place_lookup	Place Lookup
place_search	Discover (POI search)
postcode_lookup	Geocode Postcode
search_along_route	Search Along Route
static_map_image	Static Images
static_route_map	Static Images (route/path overlay)

Tool inputs always use explicit {latitude, longitude} objects; the server handles the underlying API's coordinate-order conventions internally.

Repository layout

• packages/server/ — protocol layer: the MCP server published to npm as nextbillion-mcp.
  • src/core/ — server assembly (spec compliance, error mapping)
  • src/tools/ — one file per tool, grouped by product (places / routing / maps)
  • src/nbclient/ — shared NextBillion HTTP client (auth, timeout, retry, key redaction)
  • src/transports/ — (stdio is served via the SDK entry; HTTP transport lands here later)
• distributions/ — distribution layer: zero-logic install packaging per client (Claude Code plugin, Codex plugin bundle, Cursor snippet, manual configuration).
• deploy/ — placeholder for the future hosted (Streamable HTTP) deployment.

Development

npm install
npm run typecheck
npm test          # unit + protocol conformance (no network, no key needed)
npm run build
NBAI_API_KEY=<key> npm run test:e2e   # live-API smoke tests

Test a local build interactively with the MCP Inspector:

NBAI_API_KEY=<key> npx @modelcontextprotocol/inspector node packages/server/dist/index.js