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 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@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> 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.)

Related MCP server: NextBillion.ai MCP Server

Tools

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

Privacy Policy

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.

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 Desktop extension, 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     # bundles the server into a single zero-dependency dist/index.js
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