openchargemap-mcp-server

---

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

Tool	Description
openchargemap_find_stations	Find charging stations near a point or within a bounding box, filtered by connector, power, network, usage, status, and charge points. Coordinate-native.
openchargemap_get_station	Full record for one station by numeric OCM ID — every connection, operator, access rules, charge points, cost, media, and a computed reliability note.
openchargemap_lookup_reference	Resolve connector/operator/usage/status/country names to the integer filter IDs find_stations needs. Served from a bundled snapshot — offline and instant.
openchargemap_get_station_comments	Community check-ins for one station alongside the registry status and last-verified date, so registry-vs-reality mismatch is visible.

Resources

Resource	Description
openchargemap://station/{id}	Full station record (with community comments) by numeric OCM ID — the URI-addressable twin of openchargemap_get_station.
skill://openchargemap-guide/SKILL.md	Guide to recommending compatible, accessible chargers, assessing reliability evidence, and checking search coverage. Also ships with plugin, npm, Docker, and MCPB installs.

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

2. Navigate into the directory:

cd openchargemap-mcp-server

3. Install dependencies:

bun install

4. 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 environment variables:

Variable	Description	Default
OPENCHARGEMAP_API_KEY	Required. Open Charge Map API key, sent as the X-API-Key header. Free signup at openchargemap.org.	—
OPENCHARGEMAP_BASE_URL	OCM API base URL. Override for a private mirror or testing.	https://api.openchargemap.io/v3
OPENCHARGEMAP_REFERENCE_REFRESH	When true, refresh reference data from the live /referencedata endpoint at startup, falling back to the bundled snapshot on failure. When false, stay fully offline on the bundled snapshot.	false
OPENCHARGEMAP_CLAMP_LIMITS	Clamp oversized positive integer page sizes to the tool maximum (stations 200, comments/reference 100), with a notice, log and openchargemap.pagination.clamps counter. false restores rejection. Zero, negative and fractional sizes always reject.	true
MCP_TRANSPORT_TYPE	Transport: stdio or http.	stdio
MCP_HTTP_PORT	Port for the HTTP server.	3010
MCP_AUTH_MODE	Auth mode: none, jwt, or oauth.	none
MCP_LOG_LEVEL	Log level (RFC 5424).	info
LOGS_DIR	Directory for log files (Node.js only).	<project-root>/logs
LOG_TOOL_FAILURE_PAYLOADS	Log each failed tool call's arguments and result, redacted by key name and capped at LOG_TOOL_FAILURE_PAYLOAD_MAX_BYTES (default 16384). A secret inside a free-form value is not redacted.	false
STORAGE_PROVIDER_TYPE	Storage backend.	in-memory
OTEL_ENABLED	Enable OpenTelemetry instrumentation (spans, metrics, completion logs).	false

See .env.example for the full list of optional overrides.

Running the server

Local development

• Build and run:

  # One-time build
  bun run rebuild
  
  # Run the built server
  bun run start:stdio
  # or
  bun run start:http
  

• Run checks and tests:

  bun run devcheck   # Lint, format, typecheck, security, changelog sync
  bun run test       # Vitest test suite
  bun run lint:mcp   # Validate MCP definitions against spec
  

Docker

docker build -t openchargemap-mcp-server .
docker run --rm -e OPENCHARGEMAP_API_KEY=your-key -p 3010:3010 openchargemap-mcp-server

The Dockerfile defaults to HTTP transport, stateless session mode, and logs to /var/log/openchargemap-mcp-server. OpenTelemetry peer dependencies are installed by default — build with --build-arg OTEL_ENABLED=false to omit them.

Project structure

Directory	Purpose
src/index.ts	createApp() entry point — registers tools/resources and inits services.
src/config	Server-specific environment variable parsing and validation with Zod.
src/data	Bundled Open Charge Map reference snapshot (ocm-reference-data.ts) — the offline source for ID resolution.
src/mcp-server/tools	Tool definitions (*.tool.ts) plus the shared station schema and renderers.
src/mcp-server/resources	Resource definitions (*.resource.ts).
src/services/openchargemap	OCM POI API client, response normalization, attribution, and the reliability-note helper.
src/services/reference-data	Reference-data service — snapshot loading, lookup indices, curated aliases, optional live refresh.
tests/	Unit and integration tests mirroring src/.

Development guide

See AGENTS.md (and CLAUDE.md) for development guidelines and architectural rules. The short version:

• Handlers throw, framework catches — no try/catch in tool logic
• Use ctx.log for request-scoped logging, ctx.state for tenant-scoped storage
• Register new tools and resources in the createApp() arrays
• Wrap external API calls: validate raw → normalize to domain type → return output schema; never fabricate missing fields

Attribution and data license

Charging-station, connector, and operator data is sourced from Open Charge Map, the community-maintained global registry of EV charging locations. License terms vary by data provider. Station records expose dataProviderLicense and isOpenDataLicensed when supplied; an unspecified license is unknown.

Station data © Open Charge Map contributors and the providers named on each station (openchargemap.org). License terms vary by provider.

Every tool response carries this attribution string, and the server restates it in its session-level instructions. Preserve attribution to Open Charge Map, its contributors, and each station's provider, and consult that provider's license terms before reuse. This server's own code is Apache-2.0 (below).

Contributing

Issues are welcome. Run checks and tests before submitting:

bun run devcheck
bun run test

License

Apache-2.0 — see LICENSE for details. Open Charge Map data carries its own license; see Attribution and data license.