io.github.cyanheads/openchargemap-mcp-server

Official4 toolsLive

by cyanheads · TypeScript

Find EV charging stations, detail, and reliability check-ins via the global Open Charge Map.

@cyanheads/openchargemap-mcp-server

This MCP server finds EV charging stations worldwide using the global Open Charge Map registry, based on location and connector. It provides full station detail, reference-ID resolution, and community reliability check-ins. The server runs over STDIO or Streamable HTTP and exposes 4 tools and 1 resource.

🛠️ Key Features

Discover EV charging stations via Open Charge Map
Filter by location and connector
Retrieve full station detail
Resolve reference IDs
Include community reliability check-ins
Operate via STDIO or Streamable HTTP

🚀 Use Cases

EV charging station lookup by geographic area
Connector-specific planning and matching
Accessing station details and reliability check-ins for communities

⚡ Developer Benefits

Model Context Protocol (MCP) server integration
Tool access count: 4
TypeScript project targeting EV data from Open Charge Map

⚠️ Limitations

Server description only states charging-station lookup, detail, reference resolution, and reliability check-ins; no other capabilities are documented here.

Topics

ai-agentsai-toolscharging-stationscyanheadselectric-vehiclesevev-chargingmcpmcp-servermodel-context-protocolopenchargemaptypescriptopen-charge-map

Captured live from the server via tools/list.

openchargemap_find_stations

Find EV charging stations from the global Open Charge Map registry near a point or within a bounding box. Provide either a center (latitude + longitude + distance) or a boundingbox; optionally scope to a country with countrycode. This tool is coordinate-native and does not geocode place names — resolve a place like "Ballard, Seattle" to coordinates with openstreetmap_geocode first, then pass them here. Filter by connector type, minimum power (kW), operator/network, usage type (public/free/membership), charge level, operational status, and minimum charge points. Filter IDs are integers — resolve a connector or network name to its ID with openchargemap_lookup_reference (e.g. "CCS" -> 33). Each result includes title, address, distance from the search point, connections (type, power, count), operator, access rules, registry operational status, and the last-verified date. Results come back one page at a time: when a page reports truncated, repeat the same search with the reported nextOffset to read the next one.

Parameters15

latitude	number	optional	Center latitude (WGS84 decimal degrees). Use with longitude + distance for a radius search. Resolve place names via openstreetmap_geocode first.
longitude	number	optional	Center longitude (WGS84 decimal degrees). Use with latitude + distance for a radius search.
distance	number	optional	Search radius from the center point, in the unit given by distanceUnit (default km). Max 500. Keep small (5-25) for dense urban areas; widen for rural coverage.
distanceUnit	string	optional	Unit for the distance parameter and the returned distance values.
boundingbox	object	optional	Bounding-box search as an alternative to a center+radius. Mutually exclusive with latitude/longitude/distance — sending a boundingbox alongside a latitude or a longitude is rejected, not resolved in favour of one of them.
countrycode	string	optional	Restrict to one country by ISO 3166-1 alpha-2 code (e.g. "US", "FR", "GB"). Omit for a global search. The server is global by default — there is no implicit country.
connectiontypeid	any	optional	Connector type ID, or an array of IDs (OR-matched). Resolve names with openchargemap_lookup_reference — e.g. CCS (Type 2)=33, CHAdeMO=2, NACS/Tesla Supercharger=27, Type 2 socket=25, Type 1/J1772=1.
minpowerkw	number	optional	Minimum charging power in kW across any connection at the station. Use ~50 for DC fast charging, ~150 for high-power DC. Stations whose fastest connection is below this are excluded.
operatorid	any	optional	Operator/network ID, or array of IDs (OR-matched). Resolve a network name with openchargemap_lookup_reference (category "operators") — e.g. "Tesla", "ChargePoint".
usagetypeid	any	optional	Usage/access type ID, or array (OR-matched). Resolve via openchargemap_lookup_reference (category "usagetypes") — e.g. Public=1, Public-Pay At Location=5, Public-Membership Required=4.
levelid	any	optional	Charge level ID (1=Low <2kW, 2=Medium >2kW, 3=High >40kW/fast). Array OR-matched. Use 3 as a coarse "fast charging only" filter when a specific connector is not required.
statustypeid	any	optional	Registry operational-status ID, or array (OR-matched). Resolve via openchargemap_lookup_reference (category "statustypes"). NOTE: registry status is operator-reported and can be stale — combine with dateLastVerified and openchargemap_get_station_comments to judge real-world reliability, do not treat it as ground truth.
minchargepoints	integer	optional	Minimum number of charge points (stalls) at the station. Filters out single-point locations when you need a station likely to have an open stall.
maxresults	integer	optional	Maximum stations to return, ordered by distance from the search point. Max 200.
offset	integer	optional	Matching stations to skip before the returned page, for reading past a truncated result. Repeat the same search with the nextOffset value the previous call reported. One search reaches at most 500 stations, so 499 is the deepest offset that can return one — narrow the area or add filters to reach stations beyond that. Ordering is by distance and stable, but Open Charge Map is edited continuously, so a station added or removed between pages can shift what a later offset lands on.

Raw schema

{
  "type": "object",
  "properties": {
    "latitude": {
      "description": "Center latitude (WGS84 decimal degrees). Use with longitude + distance for a radius search. Resolve place names via openstreetmap_geocode first.",
      "type": "number",
      "minimum": -90,
      "maximum": 90
    },
    "longitude": {
      "description": "Center longitude (WGS84 decimal degrees). Use with latitude + distance for a radius search.",
      "type": "number",
      "minimum": -180,
      "maximum": 180
    },
    "distance": {
      "default": 25,
      "description": "Search radius from the center point, in the unit given by distanceUnit (default km). Max 500. Keep small (5-25) for dense urban areas; widen for rural coverage.",
      "type": "number",
      "exclusiveMinimum": 0,
      "maximum": 500
    },
    "distanceUnit": {
      "default": "KM",
      "description": "Unit for the distance parameter and the returned distance values.",
      "type": "string",
      "enum": [
        "KM",
        "Miles"
      ]
    },
    "boundingbox": {
      "description": "Bounding-box search as an alternative to a center+radius. Mutually exclusive with latitude/longitude/distance — sending a boundingbox alongside a latitude or a longitude is rejected, not resolved in favour of one of them.",
      "type": "object",
      "properties": {
        "sw_lat": {
          "type": "number",
          "minimum": -90,
          "maximum": 90,
          "description": "South-west corner latitude."
        },
        "sw_lng": {
          "type": "number",
          "minimum": -180,
          "maximum": 180,
          "description": "South-west corner longitude."
        },
        "ne_lat": {
          "type": "number",
          "minimum": -90,
          "maximum": 90,
          "description": "North-east corner latitude."
        },
        "ne_lng": {
          "type": "number",
          "minimum": -180,
          "maximum": 180,
          "description": "North-east corner longitude."
        }
      },
      "required": [
        "sw_lat",
        "sw_lng",
        "ne_lat",
        "ne_lng"
      ]
    },
    "countrycode": {
      "description": "Restrict to one country by ISO 3166-1 alpha-2 code (e.g. \"US\", \"FR\", \"GB\"). Omit for a global search. The server is global by default — there is no implicit country.",
      "type": "string",
      "minLength": 2,
      "maxLength": 2,
      "pattern": "^[A-Za-z]{2}$"
    },
    "connectiontypeid": {
      "description": "Connector type ID, or an array of IDs (OR-matched). Resolve names with openchargemap_lookup_reference — e.g. CCS (Type 2)=33, CHAdeMO=2, NACS/Tesla Supercharger=27, Type 2 socket=25, Type 1/J1772=1.",
      "anyOf": [
        {
          "type": "integer",
          "exclusiveMinimum": 0,
          "maximum": 9007199254740991,
          "description": "A single reference ID."
        },
        {
          "minItems": 1,
          "maxItems": 10,
          "type": "array",
          "items": {
            "type": "integer",
            "exclusiveMinimum": 0,
            "maximum": 9007199254740991,
            "description": "A reference ID."
          },
          "description": "Several reference IDs, OR-matched. At least one."
        }
      ]
    },
    "minpowerkw": {
      "description": "Minimum charging power in kW across any connection at the station. Use ~50 for DC fast charging, ~150 for high-power DC. Stations whose fastest connection is below this are excluded.",
      "type": "number",
      "exclusiveMinimum": 0,
      "maximum": 1000
    },
    "operatorid": {
      "description": "Operator/network ID, or array of IDs (OR-matched). Resolve a network name with openchargemap_lookup_reference (category \"operators\") — e.g. \"Tesla\", \"ChargePoint\".",
      "anyOf": [
        {
          "type": "integer",
          "exclusiveMinimum": 0,
          "maximum": 9007199254740991,
          "description": "A single reference ID."
        },
        {
          "minItems": 1,
          "maxItems": 10,
          "type": "array",
          "items": {
            "type": "integer",
            "exclusiveMinimum": 0,
            "maximum": 9007199254740991,
            "description": "A reference ID."
          },
          "description": "Several reference IDs, OR-matched. At least one."
        }
      ]
    },
    "usagetypeid": {
      "description": "Usage/access type ID, or array (OR-matched). Resolve via openchargemap_lookup_reference (category \"usagetypes\") — e.g. Public=1, Public-Pay At Location=5, Public-Membership Required=4.",
      "anyOf": [
        {
          "type": "integer",
          "exclusiveMinimum": 0,
          "maximum": 9007199254740991,
          "description": "A single reference ID."
        },
        {
          "minItems": 1,
          "maxItems": 10,
          "type": "array",
          "items": {
            "type": "integer",
            "exclusiveMinimum": 0,
            "maximum": 9007199254740991,
            "description": "A reference ID."
          },
          "description": "Several reference IDs, OR-matched. At least one."
        }
      ]
    },
    "levelid": {
      "description": "Charge level ID (1=Low <2kW, 2=Medium >2kW, 3=High >40kW/fast). Array OR-matched. Use 3 as a coarse \"fast charging only\" filter when a specific connector is not required.",
      "anyOf": [
        {
          "type": "integer",
          "exclusiveMinimum": 0,
          "maximum": 9007199254740991,
          "description": "A single reference ID."
        },
        {
          "minItems": 1,
          "maxItems": 3,
          "type": "array",
          "items": {
            "type": "integer",
            "exclusiveMinimum": 0,
            "maximum": 9007199254740991,
            "description": "A reference ID."
          },
          "description": "Several reference IDs, OR-matched. At least one."
        }
      ]
    },
    "statustypeid": {
      "description": "Registry operational-status ID, or array (OR-matched). Resolve via openchargemap_lookup_reference (category \"statustypes\"). NOTE: registry status is operator-reported and can be stale — combine with dateLastVerified and openchargemap_get_station_comments to judge real-world reliability, do not treat it as ground truth.",
      "anyOf": [
        {
          "type": "integer",
          "exclusiveMinimum": 0,
          "maximum": 9007199254740991,
          "description": "A single reference ID."
        },
        {
          "minItems": 1,
          "maxItems": 10,
          "type": "array",
          "items": {
            "type": "integer",
            "exclusiveMinimum": 0,
            "maximum": 9007199254740991,
            "description": "A reference ID."
          },
          "description": "Several reference IDs, OR-matched. At least one."
        }
      ]
    },
    "minchargepoints": {
      "description": "Minimum number of charge points (stalls) at the station. Filters out single-point locations when you need a station likely to have an open stall.",
      "type": "integer",
      "exclusiveMinimum": 0,
      "maximum": 9007199254740991
    },
    "maxresults": {
      "default": 25,
      "description": "Maximum stations to return, ordered by distance from the search point. Max 200.",
      "type": "integer",
      "minimum": 1,
      "maximum": 200
    },
    "offset": {
      "default": 0,
      "description": "Matching stations to skip before the returned page, for reading past a truncated result. Repeat the same search with the nextOffset value the previous call reported. One search reaches at most 500 stations, so 499 is the deepest offset that can return one — narrow the area or add filters to reach stations beyond that. Ordering is by distance and stable, but Open Charge Map is edited continuously, so a station added or removed between pages can shift what a later offset lands on.",
      "type": "integer",
      "minimum": 0,
      "maximum": 499
    }
  },
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "additionalProperties": false
}

openchargemap_get_station

Get the full record for one Open Charge Map station by its numeric OCM ID. Returns every connection (type, level, power, current, quantity, per-connection status), the operator and network, usage and access restrictions (pay-at-location, membership, access key), the number of charge points, general comments, usage cost, the data provider, media, and verification recency. Set includeComments to also return community check-ins inline.

Parameters2

id	integer	required	Numeric OCM station ID (e.g. 145452).
includeComments	boolean	optional	Include community check-ins and comments inline in the response. Adds payload but gives the real-world reliability signal alongside the registry status. Every comment on record comes back at once, unpaged — on a station with hundreds of check-ins that is a large response, so prefer openchargemap_get_station_comments, which returns them a page at a time.

Raw schema

{
  "type": "object",
  "properties": {
    "id": {
      "type": "integer",
      "exclusiveMinimum": 0,
      "maximum": 9007199254740991,
      "description": "Numeric OCM station ID (e.g. 145452)."
    },
    "includeComments": {
      "default": false,
      "description": "Include community check-ins and comments inline in the response. Adds payload but gives the real-world reliability signal alongside the registry status. Every comment on record comes back at once, unpaged — on a station with hundreds of check-ins that is a large response, so prefer openchargemap_get_station_comments, which returns them a page at a time.",
      "type": "boolean"
    }
  },
  "required": [
    "id"
  ],
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "additionalProperties": false
}

openchargemap_lookup_reference

Resolve Open Charge Map reference data to the integer IDs that openchargemap_find_stations filters require. Pick a category and pass a name or code to resolve — "CCS" or "Tesla Supercharger" -> a connectiontypeid, "ChargePoint" -> an operatorid, "Public - Pay At Location" -> a usagetypeid, "France" or "FR" -> a country. Omit the query to browse the whole category. Large categories come back one page at a time: when a page reports truncated, repeat the call with the reported nextOffset to read the next one.

Parameters4

category	string	required	Which reference set to query. connectiontypes -> connectiontypeid; operators -> operatorid; usagetypes -> usagetypeid; statustypes -> statustypeid; currenttypes -> current type; levels -> charge level (1/2/3); countries -> ISO country.
query	string	optional	Name, title, code, or alias to resolve (e.g. "CCS", "CHAdeMO", "Tesla", "Public", "France", "FR"). Case-insensitive, matches on title, formal name, and known aliases. Omit to browse the entire category.
limit	integer	optional	Maximum entries to return when browsing or when a query matches several. Max 100.
offset	integer	optional	Entries to skip before the returned page, for reading past a truncated result. Repeat the same call with the nextOffset value the previous one reported. Applies to browsing and to a query with many matches alike; the order is stable, so every entry is reachable by paging.

Raw schema

{
  "type": "object",
  "properties": {
    "category": {
      "type": "string",
      "enum": [
        "connectiontypes",
        "operators",
        "usagetypes",
        "statustypes",
        "currenttypes",
        "levels",
        "countries"
      ],
      "description": "Which reference set to query. connectiontypes -> connectiontypeid; operators -> operatorid; usagetypes -> usagetypeid; statustypes -> statustypeid; currenttypes -> current type; levels -> charge level (1/2/3); countries -> ISO country."
    },
    "query": {
      "description": "Name, title, code, or alias to resolve (e.g. \"CCS\", \"CHAdeMO\", \"Tesla\", \"Public\", \"France\", \"FR\"). Case-insensitive, matches on title, formal name, and known aliases. Omit to browse the entire category.",
      "type": "string",
      "pattern": "\\S"
    },
    "limit": {
      "default": 25,
      "description": "Maximum entries to return when browsing or when a query matches several. Max 100.",
      "type": "integer",
      "minimum": 1,
      "maximum": 100
    },
    "offset": {
      "default": 0,
      "description": "Entries to skip before the returned page, for reading past a truncated result. Repeat the same call with the nextOffset value the previous one reported. Applies to browsing and to a query with many matches alike; the order is stable, so every entry is reachable by paging.",
      "type": "integer",
      "minimum": 0,
      "maximum": 9007199254740991
    }
  },
  "required": [
    "category"
  ],
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "additionalProperties": false
}

openchargemap_get_station_comments

Read community check-ins and comments for one Open Charge Map station — the real-world reliability signal beyond the operator-reported registry status. Returns user comments and fault reports with ratings, dates, and the outcome the driver recorded ("Charged Successfully", "Failed to Charge (Equipment Not Operational)", …), alongside the station's current registry status and last-verified date, surfacing mismatches like "listed operational, but the last few check-ins report a fault." A busy station's check-ins come back one page at a time: when a page reports truncated, repeat the call with the reported nextOffset to read the next one.

Parameters3

id	integer	required	Numeric OCM station ID.
maxresults	integer	optional	Maximum comments to return, newest first. Max 100.
offset	integer	optional	Comments to skip before the returned page, for reading past a truncated result. Repeat the same call with the nextOffset value the previous one reported. Ordering is newest-first and stable, but a check-in posted between pages shifts what a later offset lands on.

Raw schema

{
  "type": "object",
  "properties": {
    "id": {
      "type": "integer",
      "exclusiveMinimum": 0,
      "maximum": 9007199254740991,
      "description": "Numeric OCM station ID."
    },
    "maxresults": {
      "default": 25,
      "description": "Maximum comments to return, newest first. Max 100.",
      "type": "integer",
      "minimum": 1,
      "maximum": 100
    },
    "offset": {
      "default": 0,
      "description": "Comments to skip before the returned page, for reading past a truncated result. Repeat the same call with the nextOffset value the previous one reported. Ordering is newest-first and stable, but a check-in posted between pages shifts what a later offset lands on.",
      "type": "integer",
      "minimum": 0,
      "maximum": 9007199254740991
    }
  },
  "required": [
    "id"
  ],
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "additionalProperties": false
}

README.md17 KBView on GitHub

@cyanheads/openchargemap-mcp-server

Find EV charging stations worldwide by location and connector via 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

MCP SDK TypeScript

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

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`.

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, in KM or Miles, max 500) or boundingbox — exactly one mode per call; a boundingbox sent alongside a stray latitude or longitude is rejected rather than resolved by dropping the extra coordinate
Optional country scope via ISO 3166-1 alpha-2 countrycode (global by default); filters for connector type, minimum power (kW), operator/network, usage type, charge level, operational status, and minimum charge points — all integer IDs, single or OR-matched arrays, resolved via openchargemap_lookup_reference
maxresults caps the page (default 25, max 200); OCM has no offset parameter of its own, so paging runs over an over-fetched candidate page and reachable depth is 500 stations per search (offset 0–499)
totalCount is exact only when the candidate page came back short of its cap — otherwise it's a floor, and the notice says which
Local filters (minchargepoints, and the drop of OCM's 0,0 coordinate sentinels) run over the whole candidate page, so a match ranked past maxresults is not lost
Coordinate-native — does not geocode place names. Resolve a place name to coordinates with a geocoding server (e.g. the openstreetmap MCP server's openstreetmap_geocode) first

`openchargemap_get_station` _tool

Full detail for one station by its numeric OCM ID (fetched with verbose=true) — every connection (type, level, power, current, amperage, voltage, quantity), operator/network, usage and access restrictions, charge-point count, comments, usage cost, data provider, media, and verification recency
includeComments returns every check-in on record inline, unpaged — for a heavily-commented station, prefer openchargemap_get_station_comments instead
Computes a plain-prose reliabilityNote from observable facts (verification age, registry status, operational flag, fault-vs-positive check-in counts) — no synthetic score; omitted when status is fresh and uncontested
A status of "Temporarily Unavailable" or "Partly Operational (Mixed)" raises a caveat of its own, since OCM flags both as operational
Obtain an ID from openchargemap_find_stations — UUID lookup is not supported by the OCM API

`openchargemap_lookup_reference` _tool

Categories: connectiontypes, operators, usagetypes, statustypes, currenttypes, levels, countries — served from a bundled snapshot, so it makes no network call (offline, instant)
Pass a query to resolve a name, title, code, or alias ("CCS", "Tesla Supercharger", "France", "FR"), case-insensitive; omit it to browse the whole category (limit max 100, default 25), paged via offset/nextOffset
Returns the matching id(s) plus the filterParam they feed into find_stations
source is live or bundled alongside a snapshotDate; an optional startup refresh (OPENCHARGEMAP_REFERENCE_REFRESH) keeps the snapshot from drifting — on failure or when off, source stays bundled

`openchargemap_get_station_comments` _tool

Comments and fault reports with ratings, dates, and the recorded check-in outcome ("Charged Successfully", "Failed to Charge (Equipment Not Operational)", …), newest first — maxresults caps the page (default 25, max 100), paged via offset/nextOffset
totalComments is the station's whole set, not the page — reliabilityNote's fault ratio is counted over that whole set so it doesn't move with maxresults
Surfaces the station's registry status, operational flag, and dateLastVerified alongside the comments, for spotting a mismatch like "listed operational, but recent check-ins report a fault"
An empty result (comments: []) is not an error — absence of reports is not evidence the charger works
Backed by the POI fetch with includecomments=true (OCM has no standalone comments endpoint), so the whole set is available without a further upstream call
Obtain a station ID from openchargemap_find_stations

`openchargemap://station/{id}` _resource

URI-addressable twin of openchargemap_get_station — full record for one station by numeric OCM ID, with community comments always included
Response cached for 600 seconds
Not listable — the station corpus isn't enumerable by URI; discover an ID with openchargemap_find_stations
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 rather than rebuilding place-name 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:

json

{
  "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.

json

{
  "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):

json

{
  "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:

json

{
  "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

Clone the repository:

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

Navigate into the directory:

cd openchargemap-mcp-server

Install dependencies:

bun install

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`
`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`
`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, 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.

Install

Tools (4)

openchargemap_find_stationsopenchargemap_get_stationopenchargemap_lookup_referenceopenchargemap_get_station_comments

Configuration

Environment variables

OPENCHARGEMAP_API_KEYrequiredsecret

Open Charge Map API key, sent as the X-API-Key header on every request. Free instant signup at openchargemap.org.

OPENCHARGEMAP_BASE_URL

Override the OCM API base URL (default https://api.openchargemap.io/v3). For a private mirror or testing.

OPENCHARGEMAP_REFERENCE_REFRESHdefault false

When true, refresh reference data from the live /referencedata endpoint at startup, falling back to the bundled snapshot on failure.

MCP_LOG_LEVELdefault info

Sets the minimum log level for output (e.g., 'debug', 'info', 'warn').

MCP_TRANSPORT_TYPEdefault http

Selects the HTTP transport.

MCP_HTTP_HOSTdefault 127.0.0.1

The hostname for the HTTP server.

MCP_HTTP_PORTdefault 3010

The port to run the HTTP server on.

MCP_HTTP_ENDPOINT_PATHdefault /mcp

The endpoint path for the MCP server.

MCP_AUTH_MODEdefault none

Authentication mode to use: 'none', 'jwt', or 'oauth'.

Add to VS Code Add to Cursor

claude_desktop_config.json

json

{
  "mcpServers": {
    "openchargemap-mcp-server": {
      "command": "npx",
      "args": [
        "-y",
        "@cyanheads/openchargemap-mcp-server@0.1.10"
      ],
      "env": {
        "OPENCHARGEMAP_API_KEY": "<YOUR_OPENCHARGEMAP_API_KEY>",
        "OPENCHARGEMAP_BASE_URL": "<YOUR_OPENCHARGEMAP_BASE_URL>",
        "OPENCHARGEMAP_REFERENCE_REFRESH": "false",
        "MCP_LOG_LEVEL": "info"
      }
    }
  }
}

@cyanheads/openchargemap-mcp-server

🛠️ Key Features

🚀 Use Cases

⚡ Developer Benefits

⚠️ Limitations

Topics

openchargemap_find_stations

openchargemap_get_station

openchargemap_lookup_reference

openchargemap_get_station_comments

@cyanheads/openchargemap-mcp-server

Overview

Tools

Resources

Capability reference

openchargemap_find_stations tool

openchargemap_get_station tool

openchargemap_lookup_reference tool

openchargemap_get_station_comments tool

openchargemap://station/{id} resource

Features

Getting started

Public Hosted Instance

Self-Hosted / Local

Prerequisites

Installation

Configuration

Running the server

Local development

Docker

Project structure

Development guide

Attribution and data license

Contributing

License

Install

Configuration

Related servers

`openchargemap_find_stations` _tool

`openchargemap_get_station` _tool

`openchargemap_lookup_reference` _tool

`openchargemap_get_station_comments` _tool

`openchargemap://station/{id}` _resource