Openchargemap MCP Server

@cyanheads/openchargemap-mcp-server Find EV charging stations worldwide by location and connector from the global Open Charge Map registry — full station detail, reference-ID resolution, and community reliability check-ins via MCP. STDIO or Streamable HTTP. 4 Tools • 2 Resources

Public Hosted Server: https://openchargemap.caseyjhand.com/mcp

Overview

EV charging stations worldwide from Open Charge Map. Search by location, connector, and network, pull full station detail, and read community check-ins on whether a charger actually works.

Tools

Resources

All station data is also reachable via the tools; the station corpus (~200k locations, geo-scoped) isn't exposed as a listable resource, and reference data is served by openchargemap_lookup_reference rather than a resource.

Capability reference

openchargemap_find_stations tool

• Radius search (latitude + longitude + distance, distanceUnit KM or Miles, max 500) or boundingbox — exactly one mode per call; optional countrycode (ISO 3166-1 alpha-2) and filters connectiontypeid, minpowerkw, operatorid, usagetypeid, levelid, statustypeid, minchargepoints (the ID filters take one integer ID or an OR-matched array, resolved via openchargemap_lookup_reference)
• maxresults caps the page (default 25, max 200) and offset pages through a fixed cached pool of up to 500 candidates per search. A 501st record only detects an upstream remainder: totalCount is exact without that sentinel and a floor when it is present; the notice says which
• No matches returns a successful empty list with search recovery guidance. Unknown country codes are not applied and are disclosed in the summary and notice. Fails with invalid_location (no search area, half a center, or a coordinate beside a boundingbox), auth_failed, or upstream_unavailable

openchargemap_get_station tool

• Full record for one station by numeric OCM id — every connection, operator/network, usage and access rules, charge-point count, usage cost, data provider, media, and dateLastVerified; includeComments adds every check-in inline, unpaged (use openchargemap_get_station_comments for a heavily-commented station)
• reliabilityNote is plain prose computed from observable facts (verification age, registry status, operational flag, fault-vs-positive check-ins), omitted when there is nothing to flag; fails with not_found, auth_failed, or upstream_unavailable

openchargemap_lookup_reference tool

• category (connectiontypes, operators, usagetypes, statustypes, currenttypes, levels, countries) plus an optional case-insensitive query naming a title, code, or alias ("CCS", "Tesla Supercharger", "FR"); omit query to browse the category (limit max 100, default 25, paged via offset/nextOffset)
• Returns the matching id(s), the filterParam they feed into openchargemap_find_stations, and source (live or bundled) with a snapshotDate — answered offline from the bundled snapshot unless OPENCHARGEMAP_REFERENCE_REFRESH refreshed it at startup. A miss returns a successful empty list with spelling/browse guidance

openchargemap_get_station_comments tool

• Check-ins for one station by numeric OCM id, newest first, each with rating, date, and recorded outcome — maxresults caps the page (default 25, max 100), paged via offset/nextOffset; totalComments counts the station's whole set, and reliabilityNote's fault ratio is computed over all of it
• Returns the registry status, isOperational, and dateLastVerified beside the comments; an empty comments: [] is not an error (no reports is not evidence the charger works); fails with not_found, auth_failed, or upstream_unavailable

openchargemap://station/{id} resource

• Full record for one station by numeric OCM ID, community comments always included — the URI-addressable twin of openchargemap_get_station, cached for 600 seconds, and not listable
• Fails with not_found when the ID doesn't resolve to a station

Features

Built on @cyanheads/mcp-ts-core: stdio and Streamable HTTP transports, pluggable auth (none / jwt / oauth), swappable storage (in-memory, filesystem, Supabase, Cloudflare KV/R2/D1), structured logging with optional OpenTelemetry tracing.

Open Charge Map-specific:

• Type-safe client for the OCM v3 POI API with retry and session-scoped result caching
• Reference data (connectors, operators, usage/status types, countries) bundled as an offline snapshot — name→ID resolution needs no live /referencedata call, with an optional startup refresh to prevent drift
• Curated connector aliases (CCS, NACS/Supercharger, J1772, Type 2, CHAdeMO) so the names agents actually use resolve to the right IDs
• Geocoding intentionally delegated — the server is coordinate-native and composes with any geocoding MCP server (e.g. the openstreetmap server's openstreetmap_search_places) rather than rebuilding place-name lookup
• Stations are addressed by numeric OCM ID, discovered through openchargemap_find_stations — the OCM API has no UUID lookup

Agent-friendly output:

• Reliability surfaced as first-class signal — status, statusTypeId, isOperational, and dateLastVerified on every station, plus a plain-prose reliabilityNote derived only from observable facts (no fabricated confidence score)
• Honest sparsity — heavily-omitted upstream fields are optional with "absence means unknown, not zero/false" descriptions; the server never invents data OCM didn't return
• Attribution to Open Charge Map contributors and station data providers on every response; per-station provider license terms and open-data flags when supplied

Getting started

Public Hosted Instance

A public instance is available at https://openchargemap.caseyjhand.com/mcp — no installation required. Point any MCP client at it via Streamable HTTP, with this client config:

{

"mcpServers": { "openchargemap-mcp-server": { "type": "streamable-http", "url": "https://openchargemap.caseyjhand.com/mcp" } } }

Self-Hosted / Local

Add the following to your MCP client configuration file. An Open Charge Map API key is required — see Prerequisites.

{

"mcpServers": { "openchargemap-mcp-server": { "type": "stdio", "command": "bunx", "args": ["@cyanheads/openchargemap-mcp-server@latest"], "env": { "MCP_TRANSPORT_TYPE": "stdio", "MCP_LOG_LEVEL": "info", "OPENCHARGEMAP_API_KEY": "your-api-key" } } } }

Or with npx (no Bun required):

{

"mcpServers": { "openchargemap-mcp-server": { "type": "stdio", "command": "npx", "args": ["-y", "@cyanheads/openchargemap-mcp-server@latest"], "env": { "MCP_TRANSPORT_TYPE": "stdio", "MCP_LOG_LEVEL": "info", "OPENCHARGEMAP_API_KEY": "your-api-key" } } } }

Or with Docker:

{

"mcpServers": { "openchargemap-mcp-server": { "type": "stdio", "command": "docker", "args": [ "run", "-i", "--rm", "-e", "MCP_TRANSPORT_TYPE=stdio", "-e", "OPENCHARGEMAP_API_KEY=your-api-key", "ghcr.io/cyanheads/openchargemap-mcp-server:latest" ] } } }

For Streamable HTTP, set the transport and start the server:

MCP_TRANSPORT_TYPE=http MCP_HTTP_PORT=3010 OPENCHARGEMAP_API_KEY=... bun run start:http

Server listens at http://localhost:3010/mcp

Prerequisites

• Bun v1.4 or higher (or Node.js v24+).
• An Open Charge Map API key — free instant signup: register an application at openchargemap.org. Sent as the X-API-Key header on every request; the server fails fast at startup if it's unset.

Installation

1. Clone the repository:

git clone https://github.com/cyanheads/openchargemap-mcp-server.git

1. Navigate into the directory:

cd openchargemap-mcp-server

1. Install dependencies:

bun install

1. Configure environment:

cp .env.example .env

edit .env and set OPENCHARGEMAP_API_KEY

Configuration

All configuration is validated at startup via Zod schemas in src/config/server-config.ts. Key environme