openchargemap-mcp-server

openchargemap-mcp-server: lookup reference

openchargemap_lookup_reference

Read-onlyIdempotent

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. A connector name can resolve to several regional variants ("CCS" matches CCS Type 2 = 33 and CCS Type 1 = 32, the North American form) — pass every returned ID to find_stations as an array, not just the first. 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.

Input Schema

Name	Required	Description
`limit`	No	Maximum entries to return when browsing or when a query matches several. Max 100; larger positive integers are clamped unless OPENCHARGEMAP_CLAMP_LIMITS=false.
`query`	No	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.
`offset`	No	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.
`category`	Yes	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.

Output Schema

Name	Required	Description
`cap`	No	The limit that was applied.
`error`	No	Present when the call failed. Absent on success.
`shown`	No	Entries in the returned page.
`notice`	No	How to reach the entries this page left out.
`source`	No	Where these entries came from. "live" — a startup refresh from Open Charge Map returned a complete set and is what is being served. "bundled" — the snapshot shipped with the server is being served, either because the refresh is switched off or because it failed and the server fell back to the bundle.
`matches`	No	Matching reference entries, best/exact match first.
`category`	No	The reference category queried.
`truncated`	No	True when matching entries were left out of the returned page.
`nextOffset`	No	The offset to pass on an otherwise identical call to read the next page. Absent on the last page.
`totalCount`	No	Entries matching before the offset/limit page was taken — the whole category when browsing, every match when a query was given.
`attribution`	No	Attribution to Open Charge Map contributors and station data providers; license terms vary by provider.
`filterParam`	No	The find_stations input parameter these IDs feed (e.g. "connectiontypeid"). Omitted for categories with no direct filter (currenttypes; countries use countrycode).
`snapshotDate`	No	Date the reference data in this response was captured, so callers know its vintage — the day the live refresh ran when source is "live", the bundled snapshot's own capture date when source is "bundled". Read it together with source: the same date can mean either a fresh fetch or a freshly cut bundle.

Schema Changelog

Changes observed during successful MCP inspections.

Changed5 schema fields changedOct 26, 2026

changedInput schema / properties / limit / description

Previous value: -"Maximum entries to return when browsing or when a query matches several. Max 100."New value: +"Maximum entries to return when browsing or when a query matches several. Max 100; larger positive integers are clamped unless OPENCHARGEMAP_CLAMP_LIMITS=false."

changedInput schema / properties / limit / maximum

Previous value: -100New value: +9007199254740991

changedOutput schema / properties / attribution / description

Previous value: -"Required CC BY 4.0 attribution to Open Charge Map contributors."New value: +"Attribution to Open Charge Map contributors and station data providers; license terms vary by provider."

changedOutput schema / properties / error / properties / data / properties / reason / description

Previous value: -"Machine-readable failure mode. Declared by this tool: `no_match`: No reference entry in the category matched the query. Other values are possible when a failure originates below the handler."New value: +"Machine-readable failure mode."

removedOutput schema / properties / error / properties / data / properties / reason / examples
```
Removed value: -[
-  "no_match"
-]
```

Changed2 schema fields changedSep 20, 2026
- removedOutput schema / properties / matches / items / properties / formalName / anyOf
```
Removed value: -[
-  {
-    "type": "string"
-  },
-  {
-    "type": "null"
-  }
-]
```
- addedOutput schema / properties / matches / items / properties / formalName / type
```
Added value: +[
+  "string",
+  "null"
+]
```

Changed6 schema fields changedAug 25, 2026

changedInput schema / $schema

Previous value: -"http://json-schema.org/draft-07/schema#"New value: +"https://json-schema.org/draft/2020-12/schema"

addedInput schema / additionalProperties
```
Added value: +false
```

changedOutput schema / $schema

Previous value: -"http://json-schema.org/draft-07/schema#"New value: +"https://json-schema.org/draft/2020-12/schema"

addedOutput schema / anyOf

Added value: +[
+  {
+    "not": {
+      "required": [
+        "error"
+      ]
+    },
+    "required": [
+      "category",
+      "matches",
+      "snapshotDate",
+      "source",
+      "attribution",
+      "totalCount"
+    ]
+  },
+  {
+    "required": [
+      "error"
+    ]
+  }
+]

addedOutput schema / properties / error

Added value: +{
+  "additionalProperties": {},
+  "description": "Present when the call failed. Absent on success.",
+  "properties": {
+    "code": {
+      "description": "JSON-RPC error code for this failure.",
+      "maximum": 9007199254740991,
+      "minimum": -9007199254740991,
+      "type": "integer"
+    },
+    "data": {
+      "additionalProperties": {},
+      "properties": {
+        "reason": {
+          "description": "Machine-readable failure mode. Declared by this tool: `no_match`: No reference entry in the category matched the query. Other values are possible when a failure originates below the handler.",
+          "examples": [
+            "no_match"
+          ],
+          "type": "string"
+        },
+        "recovery": {
+          "additionalProperties": {},
+          "description": "Actionable next step for the caller.",
+          "properties": {
+            "hint": {
+              "type": "string"
+            }
+          },
+          "required": [
+            "hint"
+          ],
+          "type": "object"
+        },
+        "retryable": {
+          "description": "Whether retrying may succeed.",
+          "type": "boolean"
+        }
+      },
+      "type": "object"
+    },
+    "message": {
+      "description": "Human-readable description of what went wrong.",
+      "type": "string"
+    }
+  },
+  "required": [
+    "code",
+    "message"
+  ],
+  "type": "object"
+}

removedOutput schema / required

Removed value: -[
-  "category",
-  "matches",
-  "snapshotDate",
-  "source",
-  "attribution",
-  "totalCount"
-]

Changed9 schema fields changedAug 6, 2026

addedInput schema / properties / offset

Added value: +{
+  "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.",
+  "maximum": 9007199254740991,
+  "minimum": 0,
+  "type": "integer"
+}

addedOutput schema / properties / nextOffset

Added value: +{
+  "description": "The offset to pass on an otherwise identical call to read the next page. Absent on the last page.",
+  "type": "number"
+}

changedOutput schema / properties / notice / description

Previous value: -"How to reach the entries beyond the cap when a browse was capped."New value: +"How to reach the entries this page left out."

changedOutput schema / properties / shown / description

Previous value: -"Number of entries returned when the cap was hit."New value: +"Entries in the returned page."

changedOutput schema / properties / snapshotDate / description

Previous value: -"Date the bundled reference snapshot was captured, so callers know the data vintage."New value: +"Date the reference data in this response was captured, so callers know its vintage — the day the live refresh ran when source is \"live\", the bundled snapshot's own capture date when source is \"bundled\". Read it together with source: the same date can mean either a fresh fetch or a freshly cut bundle."

addedOutput schema / properties / source

Added value: +{
+  "description": "Where these entries came from. \"live\" — a startup refresh from Open Charge Map returned a complete set and is what is being served. \"bundled\" — the snapshot shipped with the server is being served, either because the refresh is switched off or because it failed and the server fell back to the bundle.",
+  "enum": [
+    "live",
+    "bundled"
+  ],
+  "type": "string"
+}

changedOutput schema / properties / totalCount / description

Previous value: -"Number of entries returned."New value: +"Entries matching before the offset/limit page was taken — the whole category when browsing, every match when a query was given."

changedOutput schema / properties / truncated / description

Previous value: -"True when a browse was capped at limit."New value: +"True when matching entries were left out of the returned page."

changedOutput schema / required

Previous value: -[
-  "category",
-  "matches",
-  "snapshotDate",
-  "attribution",
-  "totalCount"
-]New value: +[
+  "category",
+  "matches",
+  "snapshotDate",
+  "source",
+  "attribution",
+  "totalCount"
+]

Changed3 schema fields changedAug 6, 2026
- removedInput schema / properties / query / minLength
```
Removed value: -1
```
- addedInput schema / properties / query / pattern
```
Added value: +"\\S"
```
- changedOutput schema / properties / notice / description
```
Previous value: -"Guidance when a query matched nothing."New value: +"How to reach the entries beyond the cap when a browse was capped."
```

Changed2 schema fields changedJul 4, 2026

changedOutput schema / properties / matches / description

Previous value: -"Matching reference entries, best/exact match first. Use the id in a find_stations filter."New value: +"Matching reference entries, best/exact match first."

changedOutput schema / properties / matches / items / properties / id / description

Previous value: -"The reference ID — pass to the matching openchargemap_find_stations filter (e.g. connectiontypeid)."New value: +"The reference ID for this entry."

First observedJun 16, 2026

TDQS

A4.8/5.0

Behavior5/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Annotations already cover the safety profile (readOnly, idempotent, closed-world), and the description adds genuinely non-obvious behavior: one name can resolve to several regional variants (CCS Type 2 = 33 vs CCS Type 1 = 32), large categories are paginated, a truncated page reports a nextOffset, and ordering is stable so paging is exhaustive. That is context an agent cannot get from the structured fields.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness4/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Front-loaded with the purpose and dense throughout — the regional-variant warning and the pagination instruction both earn their sentences. It is a single long paragraph with no visual separation between the three distinct behaviors, which slightly hurts scannability.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness5/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Output schema exists, so return values need not be spelled out; the description nonetheless covers the one return-value detail that changes caller behavior (truncated flag plus nextOffset). For a 4-parameter read-only resolver with full schema coverage, nothing an agent needs in order to call it correctly is missing.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters4/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 100%, so the baseline is 3; the description still earns a bump by tying each category value to the specific ID field it produces and by giving worked query examples ("Tesla Supercharger", "Public - Pay At Location", "FR"). It does not address limit clamping or the offset/nextOffset contract in depth beyond what the schema already states.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

States a specific verb and resource — resolving Open Charge Map reference data into the integer IDs that find_stations filters require — and names the downstream sibling that consumes the output. An agent can tell this apart from openchargemap_find_stations / get_station without opening any schema.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines5/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

Gives explicit when-to-use (before filtering find_stations), concrete call shapes per category ("CCS" -> connectiontypeid, "France" -> a country), and an explicit alternative mode (omit the query to browse). It also instructs passing all returned IDs as an array rather than just the first, which is the main misuse failure mode.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

All openchargemap-mcp-server tools Inspect

Try in Browser

One endpoint for every MCP toolRayrun runs every MCP server behind one URL and holds the credentials. Each call is decided per client, tool, and argument, then recorded.ray.runAd

Glama MCP Gateway

Add one secure layer between your agents and this server.