@cyanheads/openchargemap-mcp-server

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.

Related MCP server: @cyanheads/openstreetmap-mcp-server

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:

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

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.