openchargemap-mcp-server

---

概述

通过 Open Charge Map 获取世界各地的电动汽车充电站信息。按位置、连接器和网络搜索，获取完整站点详情，并查看社区对充电器是否正常工作的打卡反馈。

工具

工具	描述
openchargemap_find_stations	查找某个点附近或边界框内的充电站，可按连接器、功率、网络、用途、状态和充电点筛选。直接使用坐标。
openchargemap_get_station	按数字 OCM ID 获取单个站点的完整记录 — 包括所有连接、运营商、访问规则、充电点、费用、媒体，以及计算得出的可靠性说明。
openchargemap_lookup_reference	将连接器、运营商、用途、状态和国家名称解析为 find_stations 所需的整数筛选 ID。数据来自捆绑快照 — 无需联网，即时返回。
openchargemap_get_station_comments	获取某个站点的社区打卡信息，并附上登记状态和最后验证日期，从而直观看到登记信息与实际情况是否一致。

资源

资源	描述
openchargemap://station/{id}	按数字 OCM ID 查询完整站点记录（含社区评论）——是 openchargemap_get_station 的 URI 可寻址对应项。
skill://openchargemap-guide/SKILL.md	有关推荐兼容且无障碍的充电桩、评估可靠性证据和检查搜索覆盖范围的指南。插件、npm、Docker 和 MCPB 安装包也包含此指南。

所有站点数据也可通过工具访问；站点语料库（约 20 万个位置，按地理范围限定）不作为可列出资源公开，参考数据则由 openchargemap_lookup_reference 提供，而非作为资源提供。

能力参考

openchargemap_find_stations _工具

• 半径搜索（latitude + longitude + distance，distanceUnit 为 KM 或 Miles，最大值为 500）或 boundingbox——每次调用只能使用一种模式；可选的 countrycode（ISO 3166-1 alpha-2）和筛选条件 connectiontypeid、minpowerkw、operatorid、usagetypeid、levelid、statustypeid、minchargepoints（ID 筛选条件接受一个整数 ID 或按 OR 匹配的数组，并通过 openchargemap_lookup_reference 解析）
• maxresults 限制每页结果数（默认 25，最大 200），offset 用于分页浏览每次搜索缓存的固定候选池（最多 500 条）。第 501 条记录仅用于检测上游是否还有剩余结果：没有这条标记记录时，totalCount 为精确值；存在时则为下限值；notice 会说明具体情况
• 无匹配项时会成功返回空列表，并提供搜索恢复建议。未知国家代码不会应用，并会在摘要和提示中说明。失败时返回 invalid_location（未指定搜索区域、只提供了一个中心坐标，或在 boundingbox 旁提供坐标）、auth_failed 或 upstream_unavailable

---

openchargemap_get_station _工具

• 按数字 OCM id 获取单个站点的完整记录——包括每个充电接口、运营商/网络、使用和访问规则、充电点数量、使用费用、数据提供方、媒体以及 dateLastVerified；includeComments 会在结果中内联添加所有签到记录，不分页（评论很多的站点请使用 openchargemap_get_station_comments）
• reliabilityNote 根据可观察事实（验证时间、注册状态、运行标记、故障与正面签到）生成纯文本说明；无须提示时会省略。失败时返回 not_found、auth_failed 或 upstream_unavailable

---

openchargemap_lookup_reference _工具

• category（connectiontypes、operators、usagetypes、statustypes、currenttypes、levels、countries）以及可选的、不区分大小写的 query，用于指定名称、代码或别名（"CCS"、"Tesla Supercharger"、"FR"）；省略 query 可浏览该类别（limit 最大 100，默认 25，通过 offset/nextOffset 分页）
• 返回匹配项的 id，以及它们传递给 openchargemap_find_stations 的 filterParam、source（live 或 bundled）和 snapshotDate——除非 OPENCHARGEMAP_REFERENCE_REFRESH 在启动时刷新了快照，否则将使用捆绑快照离线作答。未找到时会成功返回空列表，并提供拼写或浏览建议

---

openchargemap_get_station_comments _工具

• 按数字 OCM id 获取单个站点的签到记录，按时间从新到旧排列，每条记录包含评分、日期和记录的结果——maxresults 限制每页结果数（默认 25，最大 100），通过 offset/nextOffset 分页；totalComments 统计该站点的全部记录，reliabilityNote 中的故障比例也基于全部记录计算
• 在评论旁返回注册状态、isOperational 和 dateLastVerified；空的 comments: [] 不代表错误（没有报告并不能证明充电桩可用）；失败时返回 not_found、auth_failed 或 upstream_unavailable

---

openchargemap://station/{id} _资源

• 根据数字 OCM ID 获取单个站点的完整记录，始终包含社区评论——这是 openchargemap_get_station 可通过 URI 访问的对应项，缓存 600 秒，且不可列出
• 如果 ID 无法对应到站点，则返回 not_found

功能

基于 @cyanheads/mcp-ts-core 构建：支持 stdio 和 Streamable HTTP 传输、可插拔身份验证（none / jwt / oauth）、可替换存储（in-memory、filesystem、Supabase、Cloudflare KV/R2/D1），以及支持可选 OpenTelemetry 跟踪的结构化日志。

Open Charge Map 专属功能：

• 面向 OCM v3 POI API 的类型安全客户端，支持重试和会话范围的结果缓存
• 参考数据（连接器、运营商、使用/状态类型、国家/地区）以离线快照形式打包——名称→ID 的解析无需实时调用 /referencedata，也可选择在启动时刷新以防数据偏差
• 精选连接器别名（CCS、NACS/Supercharger、J1772、Type 2、CHAdeMO），确保 Agent 实际使用的名称能解析为正确的 ID
• 有意将地理编码交由其他服务处理——本服务以坐标为原生输入，可与任意地理编码 MCP 服务组合使用（例如 openstreetmap 服务的 openstreetmap_search_places），而非重新构建地点名称查询功能
• 通过 openchargemap_find_stations 发现站点，并使用数字 OCM ID 定位——OCM API 不支持通过 UUID 查询

面向 Agent 的输出：

• 将可靠性作为一等信号呈现——每个站点均提供 status、statusTypeId、isOperational 和 dateLastVerified，另附仅根据可观察事实生成的白话说明 reliabilityNote（不编造置信度评分）
• 如实呈现数据稀疏性——上游经常省略的字段设为可选，并说明“缺失表示未知，而非零/否”；本服务绝不编造 OCM 未返回的数据
• 每个响应均注明 Open Charge Map 贡献者和站点数据提供方；如有提供，还会附上每个站点的数据提供方许可条款和开放数据标记

开始使用

公共托管实例

可使用公共实例 https://openchargemap.caseyjhand.com/mcp，无需安装。通过 Streamable HTTP 将任意 MCP 客户端指向该实例，并使用以下客户端配置：

{
  "mcpServers": {
    "openchargemap-mcp-server": {
      "type": "streamable-http",
      "url": "https://openchargemap.caseyjhand.com/mcp"
    }
  }
}

自托管 / 本地运行

将以下内容添加到 MCP 客户端配置文件中。需要 Open Charge Map API 密钥——请参阅先决条件。

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

也可使用 npx（无需 Bun）：

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

或使用 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"
      ]
    }
  }
}

对于 Streamable HTTP，请设置传输方式并启动服务：

MCP_TRANSPORT_TYPE=http MCP_HTTP_PORT=3010 OPENCHARGEMAP_API_KEY=... bun run start:http
# Server listens at http://localhost:3010/mcp

先决条件

• Bun v1.4 或更高版本（或 Node.js v24+）。
• Open Charge Map API 密钥——免费即时注册：在 openchargemap.org 注册应用。每次请求都会通过 X-API-Key 标头发送该密钥；如果未设置，本服务会在启动时立即报错。

安装

1. 克隆代码库：

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

2. 进入目录：

cd openchargemap-mcp-server

3. 安装依赖：

bun install

4. 配置环境：

cp .env.example .env
# edit .env and set OPENCHARGEMAP_API_KEY

配置

所有配置都会在启动时通过 src/config/server-config.ts 中的 Zod 模式进行验证。主要环境变量：

变量	描述	默认值
OPENCHARGEMAP_API_KEY	必填。 Open Charge Map API 密钥，通过 X-API-Key 标头发送。可在 openchargemap.org 免费注册。	—
OPENCHARGEMAP_BASE_URL	OCM API 基础 URL。可覆盖此值以使用私有镜像或进行测试。	https://api.openchargemap.io/v3
OPENCHARGEMAP_REFERENCE_REFRESH	为 true 时，启动时从实时 /referencedata 端点刷新参考数据；若失败，则回退到捆绑的快照。为 false 时，完全离线使用捆绑的快照。	false
OPENCHARGEMAP_CLAMP_LIMITS	将超出范围的正整数页面大小限制到工具上限（站点为 200，评论/参考数据为 100），并显示提示、记录日志和递增 openchargemap.pagination.clamps 计数器。设为 false 可恢复为拒绝请求。零、负数和小数大小始终会被拒绝。	true
MCP_TRANSPORT_TYPE	传输方式：stdio 或 http。	stdio
MCP_HTTP_PORT	HTTP 服务端口。	3010
MCP_AUTH_MODE	认证模式：none、jwt 或 oauth。	none
MCP_LOG_LEVEL	日志级别（RFC 5424）。	info
LOGS_DIR	日志文件目录（仅 Node.js）。	<project-root>/logs
LOG_TOOL_FAILURE_PAYLOADS	记录每次失败工具调用的参数和结果，按键名脱敏，并限制为 LOG_TOOL_FAILURE_PAYLOAD_MAX_BYTES（默认 16384）字节。自由格式值中的机密不会被脱敏。	false
STORAGE_PROVIDER_TYPE	存储后端。	in-memory
OTEL_ENABLED	启用 OpenTelemetry 监测（跨度、指标、完成日志）。	false

可选覆盖项的完整列表请参见 .env.example。

运行服务

本地开发

• 构建并运行：

  # One-time build
  bun run rebuild
  
  # Run the built server
  bun run start:stdio
  # or
  bun run start:http
  

• 运行检查和测试：

  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

Dockerfile 默认使用 HTTP 传输、无状态会话模式，并将日志写入 /var/log/openchargemap-mcp-server。默认会安装 OpenTelemetry 对等依赖项；构建时使用 --build-arg OTEL_ENABLED=false 可省略这些依赖项。

项目结构

目录	用途
src/index.ts	createApp() 入口点——注册工具/资源并初始化服务。
src/config	使用 Zod 解析并验证服务专用的环境变量。
src/data	捆绑的 Open Charge Map 参考数据快照（ocm-reference-data.ts）——用于 ID 解析的离线数据源。
src/mcp-server/tools	工具定义（*.tool.ts）以及共享的站点模式和渲染器。
src/mcp-server/resources	资源定义（*.resource.ts）。
src/services/openchargemap	OCM POI API 客户端、响应规范化、归属信息和可靠性备注辅助程序。
src/services/reference-data	参考数据服务——快照加载、查找索引、精选别名和可选的实时刷新。
tests/	与 src/ 目录结构对应的单元测试和集成测试。

开发指南

开发指南和架构规则请参见 AGENTS.md（以及 CLAUDE.md）。简而言之：

• 处理程序负责抛出错误，框架负责捕获——工具逻辑中不要使用 try/catch
• 使用 ctx.log 进行请求范围的日志记录，使用 ctx.state 存储租户范围的数据
• 在 createApp() 数组中注册新工具和资源
• 封装外部 API 调用：验证原始数据 → 规范化为领域类型 → 返回输出模式；绝不伪造缺失字段

署名与数据许可

充电站、连接器和运营商数据来自 Open Charge Map，这是一个由社区维护的全球电动汽车充电地点注册库。许可条款因数据提供方而异。站点记录在提供相关信息时会公开 dataProviderLicense 和 isOpenDataLicensed；未注明许可时，许可状态未知。

站点数据 © Open Charge Map 贡献者及各站点所列的数据提供方（openchargemap.org）。许可条款因提供方而异。

每个工具响应都会附带此 attribution 字符串，服务也会在会话级 instructions 中重申该内容。请保留对 Open Charge Map、其贡献者及各站点数据提供方的署名，并在复用数据前查阅相应提供方的许可条款。本服务自身的代码采用 Apache-2.0 许可（见下文）。

贡献

欢迎提交问题。提交前请运行检查和测试：

bun run devcheck
bun run test

许可

Apache-2.0 — 详情请参阅 LICENSE。Open Charge Map 数据遵循其自身的许可；请参阅署名与数据许可。