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

TableJSON Schema

Name	Required	Description
`limit`	No	Maximum entries to return when browsing or when a query matches several. Max 100.
`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

TableJSON 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	Required CC BY 4.0 attribution to Open Charge Map contributors.
`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.

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.5/5.0

Behavior4/5

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

Annotations already provide readOnlyHint and idempotentHint, so safety is covered. The description adds meaningful behavioral context beyond annotations: pagination behavior for large categories, truncation reporting, repeat-with-nextOffset semantics, and the ability to browse by omitting the query. This is valuable operational detail not present in the annotations.

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

Conciseness5/5

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

The description is compact and front-loaded with the core purpose, then gives useful examples and paging instructions. Every sentence earns its place; there is no filler or repetition of schema details.

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?

The description, combined with a fully described input schema, detailed annotations, and an output schema, covers all the operational knowledge needed: what to pass, how browsing works, how paging works, and how the results relate to the sibling find_stations tool. Nothing essential 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 coverage is 100%, so the baseline is 3, but the description adds real semantic value: it gives concrete examples tying categories to ID fields, clarifies that query is case-insensitive and matches aliases, and explains how offset interacts with truncated pages. This goes beyond the schema's structural descriptions.

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?

The description states a specific verb and resource: it resolves Open Charge Map reference data into the integer IDs required by openchargemap_find_stations filters. Concrete examples like 'CCS' -> connectiontypeid and 'France' -> country make the purpose unmistakable and clearly distinguish it from the station-related sibling tools.

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

Usage Guidelines4/5

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

The description clearly ties the tool to a prerequisite step for openchargemap_find_stations and explains how to browse or resolve values. It does not explicitly state when not to use this tool versus siblings, but the examples and explicit mention of find_stations provide strong contextual guidance.

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.