BeMap MCP server

Gives your AI coding assistant (Claude, Codex, Gemini CLI, Cursor, Copilot and others) the BeNomad BeMap API: every operation and field, and what most values mean. The assistant looks things up instead of guessing, and checks each request before it is sent.

Package @benomad/bemap-mcp · v0.0.1-dev.134

What your assistant gets#

Documentation, and the small program that serves it:

• the BeMap API reference (operations, fields, types, allowed values) generated from BeMap's own OpenAPI specification, with what BeMap's code declares about it: what most values mean, and the role a service needs where its endpoint declares one;
• BeNomad Tiles' API reference, from its own specification;
• BeMap's guides and SDK pages, with its tutorials in corrected copies checked against production;
• the service limits of BeMap's production (points per request, radii…);
• a skill: plain-text advice on choosing a service and avoiding BeMap's traps, with example requests and responses, for every assistant but Claude Desktop, which loads no skill from an extension.

No BeMap source code, no account or customer data, no map data, no calculation engine: the only results in it are documentation examples. It works offline and without an account; only sending a real request needs one.

Install#

Download from https://github.com/BeNomadSAS/bemap-mcp/releases, the newest release, under Assets: benomad-bemap-<version>.mcpb for Claude Desktop, benomad-bemap-mcp-<version>.tgz for every other assistant. Or clone the repository instead of taking the .tgz (step 1).

A BeMap account is needed only to send live requests; reading the documentation works without one.

Claude Desktop: the extension#

Download benomad-bemap-<version>.mcpb from the release's Assets and double-click it, or open Settings → Extensions → Advanced settings → Install Extension… and pick it. Claude Desktop runs it with its own Node.js. Fill in your BeMap account in the extension's settings, or leave them empty to read the documentation only. The key is kept in your system keychain.

Desktop loads no skill from an extension: the tools work, the skill's advice (step 3 below) is not there. To upgrade, install the new .mcpb.

Every other assistant#

You need Node.js 18 or later.

1. Install the package#

Download benomad-bemap-mcp-<version>.tgz from the release's Assets, then:

mkdir -p ~/bemap-mcp && cd ~/bemap-mcp
npm init -y >/dev/null
npm install /path/to/benomad-bemap-mcp-<version>.tgz

In Windows PowerShell:

New-Item -ItemType Directory -Force -Path "$HOME\bemap-mcp" | Out-Null
Set-Location "$HOME\bemap-mcp"
npm init -y | Out-Null
npm install C:\path\to\benomad-bemap-mcp-<version>.tgz

Or from the repository: the easiest to keep up to date. The same in a terminal and in PowerShell:

cd ~
git clone https://github.com/BeNomadSAS/bemap-mcp.git
cd bemap-mcp
npm install

Take one way, not both. From a clone, the server in step 2 is src/index.js in that folder, instead of node_modules/@benomad/bemap-mcp/src/index.js.

2. Register it#

Claude Code, in a terminal or in VS Code, it is the same registration. The claude command needs the Claude Code CLI: the VS Code extension alone does not add it. From that folder:

claude mcp add -s user bemap \
  --env BEMAP_USER=your-account \
  --env BEMAP_KEY=your-api-key \
  --env BEMAP_ENV=prod \
  -- node "$(pwd)/node_modules/@benomad/bemap-mcp/src/index.js"

In PowerShell, on one line: keep the quotes around '--': without them, PowerShell drops it when claude was installed with npm, and the command fails.

claude mcp add -s user bemap --env BEMAP_USER=your-account --env BEMAP_KEY=your-api-key --env BEMAP_ENV=prod '--' node "$PWD\node_modules\@benomad\bemap-mcp\src\index.js"

• Leave out the three --env to read the documentation only.
• prod is the environment you build on; beta lets you try what is coming.
• -s user makes the server available in every project.
• Already registered? Run claude mcp remove bemap -s user first. In VS Code, then click Reconnect next to bemap in the MCP servers panel.

Type your account and key in your own terminal, never in a conversation with the assistant.

Other assistants use the same server, each in its own configuration file. Give the absolute path to node_modules/@benomad/bemap-mcp/src/index.js (with forward slashes on Windows) and drop env to read the documentation only.

{
  "mcpServers": {
    "bemap": {
      "command": "node",
      "args": ["/absolute/path/to/node_modules/@benomad/bemap-mcp/src/index.js"],
      "env": { "BEMAP_USER": "your-account", "BEMAP_KEY": "your-api-key", "BEMAP_ENV": "prod" }
    }
  }
}

{
  "servers": {
    "bemap": {
      "type": "stdio",
      "command": "node",
      "args": ["/absolute/path/to/node_modules/@benomad/bemap-mcp/src/index.js"],
      "env": { "BEMAP_USER": "your-account", "BEMAP_KEY": "your-api-key", "BEMAP_ENV": "prod" }
    }
  }
}

{
  "mcpServers": {
    "bemap": {
      "command": "node",
      "args": ["/absolute/path/to/node_modules/@benomad/bemap-mcp/src/index.js"],
      "env": { "BEMAP_USER": "your-account", "BEMAP_KEY": "your-api-key", "BEMAP_ENV": "prod" }
    }
  }
}

[mcp_servers.bemap]
command = "node"
args = ["/absolute/path/to/node_modules/@benomad/bemap-mcp/src/index.js"]
env = { BEMAP_USER = "your-account", BEMAP_KEY = "your-api-key", BEMAP_ENV = "prod" }
tool_timeout_sec = 180

{
  "mcpServers": {
    "bemap": {
      "command": "node",
      "args": ["/absolute/path/to/node_modules/@benomad/bemap-mcp/src/index.js"],
      "env": { "BEMAP_USER": "your-account", "BEMAP_KEY": "your-api-key", "BEMAP_ENV": "prod" }
    }
  }
}

{
  "context_servers": {
    "bemap": {
      "command": "node",
      "args": ["/absolute/path/to/node_modules/@benomad/bemap-mcp/src/index.js"],
      "env": { "BEMAP_USER": "your-account", "BEMAP_KEY": "your-api-key", "BEMAP_ENV": "prod" }
    }
  }
}

3. Install the skill#

From the folder you installed the package in (~/bemap-mcp):

npx --no-install bemap-install-skill

From a clone, in the clone: node scripts/install-skill.js.

It writes the skill where the assistants read it: ~/.claude/skills/ and ~/.agents/skills/. Run it again after every upgrade; with --check it says whether your copy is current. Then restart your assistant. Run from another folder, npx would look for the name on the public npm registry.

Check it works#

Ask your assistant:

Using the bemap tools, what are the required parameters for a routing request?

The answer names destinations.

If something is wrong#

• The assistant does not see the tools: check claude mcp list (or /mcp in Claude Code's VS Code panel), then restart the assistant.
• "BeMap rejected the credentials": check the account and the key, and that the account exists on the environment you chose.
• 400 Access Denied: the account lacks that service's entitlement. Ask BeNomad to provision it.
• 403 "Wrong site": the key's use is locked to a web site, and the assistant is not one: use a key without that restriction.
• A field does not exist on your environment: bemap_status says which BeMap release the package describes, and whether yours runs it.
• "timed out after 120000 ms": a long EV route can take longer: add BEMAP_TIMEOUT_SECONDS=300 to the server's env, and in Codex raise tool_timeout_sec with it. Claude Desktop may stop waiting after about a minute, whatever the extension's timeout setting.
• A live call fails with a certificate error (UNABLE_TO_VERIFY_LEAF_SIGNATURE, SELF_SIGNED_CERT_IN_CHAIN): your network uses its own certificate authority: add NODE_EXTRA_CA_CERTS=/path/to/company-ca.pem to the server's env (in Claude Desktop, "Company certificate file").
• Every live call fails behind a proxy: live calls go straight to BeMap and do not use HTTPS_PROXY. Check requests with validateOnly, or use a network that reaches BeMap directly.
• "is plain HTTP … nothing is sent": your own installation's address starts with http://: use its https:// address, or, on a network you trust, add BEMAP_ALLOW_INSECURE_HTTP=1 (in Claude Desktop, "Allow plain HTTP").

Upgrading#

• Claude Desktop: install the new .mcpb.
• The package: install the new .tgz the same way, then, from that folder, npx --no-install bemap-install-skill again.
• A clone: git pull, npm install, then node scripts/install-skill.js.

Then restart your assistant.

Support#

bgis-support@benomad.com

Get the package

The package on GitHub