io.github.cyanheads/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 • 1 Resource

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

Overview

EV charging stations from the global Open Charge Map registry. Search by location and connector, pull full station detail, resolve connector and network names to filter IDs, and read community reliability check-ins from any MCP client. Runs as a stdio process, a local Streamable HTTP server, or the public hosted endpoint above.

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 up to 500 stations per search; totalCount is exact only when OCM's candidate page came back short of its cap — otherwise it's a floor, and the notice says which
• Fails with invalid_location (no search area, half a center, or a coordinate beside a boundingbox), no_stations, 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; fails with no_match

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
• CC BY 4.0 attribution on every tool response and in the server-level instructions, per the data license

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 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, and is licensed under **CC BY 4.0**.

Station data © Open Charge Map contributors, licensed under CC BY 4.0 (openchargemap.org).

Attribution is mandatory: every tool response carries this attribution string, and the server restates it in its session-level instructions. Any downstream use of the data must credit Open Charge Map and its contributors. This server's own code is Apache-2.0 (below); the license terms above apply to the data, not the software.

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.