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.
Get an API key from console.nextbillion.ai or by emailing
support@nextbillion.ai, and export it as NBAI_API_KEY in your shell profile.
Claude Desktop extension: download nextbillion-mcp-<version>.mcpb from the
latest release, open it
(or Settings → Extensions → Advanced settings → Install Extension…), and paste your API key when
prompted. The server is bundled, so no Node.js install is needed. Details in
distributions/claude-desktop/README.md.
Claude Code plugin (this repository doubles as a plugin marketplace):
claude plugin marketplace add nextbillion-ai/nextbillion-mcp
claude plugin install nextbillion-mcp@nextbillionAny MCP client — snippets for Claude Code, Cursor, and Codex are in
distributions/manual/README.md. The short version:
NBAI_API_KEY=<your key> npm_config_audit=false npx -y nextbillion-mcp(The Claude Code plugin runs a bundled copy of the server directly — no npx, no network at
startup. For npx-based setups, npm_config_audit=false skips npm's post-install audit call,
which hangs on some networks; see distributions/manual/README.md.)
| 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_browse |
Browse (places by category near a location) |
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.
nextbillion-mcp is a local MCP server: it runs on your own machine, is started by your
MCP client, and communicates only with the NextBillion.ai API. NextBillion.ai's privacy
policy applies to the API service: https://nextbillion.ai/privacy.
What is collected and sent. When your AI client calls a tool, the server sends that
tool call's arguments (for example addresses, place names, coordinates, route and map
parameters) to api.nextbillion.io over HTTPS, authenticated with your API key, and
returns the API's response to your client unchanged. The server does not collect or
transmit anything else: no conversation content beyond the tool arguments, no files, no
device or usage information. The server does not query your client's memory, chat history
or files.
Telemetry. None. The server contains no analytics, crash reporting or update checks;
its only network destination is the NextBillion.ai API (configurable via NBAI_BASE_URL).
API key handling. The key is read from the NBAI_API_KEY environment variable
supplied by your client configuration, kept in memory for the life of the process, sent
only to the NextBillion.ai API, and redacted from error messages and logs. It is never
written to disk by the server.
Local storage. Nothing is stored locally by default. If you set NBAI_IMAGE_DIR, the
two map tools additionally save each rendered map image to that directory so that
terminal clients can open it; those files are yours to keep or delete, and the server
never overwrites existing files. Diagnostics go to the process's standard error stream,
which your client may capture in its own logs.
Third-party sharing and retention. The server shares data with no one other than NextBillion.ai. How NextBillion.ai uses and retains API request data is described in its privacy policy at https://nextbillion.ai/privacy.
Contact. Privacy or support questions: support@nextbillion.ai.
packages/server/— protocol layer: the MCP server published to npm asnextbillion-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 Desktop extension, Claude Code plugin, Codex plugin bundle, Cursor snippet, manual configuration).deploy/— placeholder for the future hosted (Streamable HTTP) deployment.
npm install
npm run typecheck
npm test # unit + protocol conformance (no network, no key needed)
npm run build # bundles the server into a single zero-dependency dist/index.js
NBAI_API_KEY=<key> npm run test:e2e # live-API smoke testsTest a local build interactively with the MCP Inspector:
NBAI_API_KEY=<key> npx @modelcontextprotocol/inspector node packages/server/dist/index.js