openchargemap-mcp-server

---

概要

Open Charge Mapから、世界中のEV充電ステーションを検索できます。場所、コネクター、ネットワークで検索し、ステーションの詳細情報や、充電器が実際に使えるかどうかに関するコミュニティのチェックインを確認できます。

ツール

ツール	説明
openchargemap_find_stations	地点周辺または境界ボックス内の充電ステーションを、コネクター、出力、ネットワーク、利用方法、ステータス、充電ポイントで絞り込んで検索します。座標を直接指定できます。
openchargemap_get_station	数値のOCM IDで指定した1つのステーションの完全なレコードを取得します。すべての接続、運営者、アクセス規則、充電ポイント、料金、メディア、および算出された信頼性に関する注記を確認できます。
openchargemap_lookup_reference	コネクター、運営者、利用方法、ステータス、国の名前を、find_stationsで必要な整数のフィルターIDに解決します。バンドルされたスナップショットから提供されるため、オフラインで即座に利用できます。
openchargemap_get_station_comments	1つのステーションに関するコミュニティのチェックインを、レジストリのステータスおよび最終確認日とともに取得し、レジストリの情報と実際の状況の不一致を確認できます。

リソース

リソース	説明
openchargemap://station/{id}	数値の OCM ID で指定した、コミュニティコメントを含むステーションの全レコードです。openchargemap_get_station に対応する URI でアクセス可能なリソースです。
skill://openchargemap-guide/SKILL.md	互換性とアクセシビリティに優れた充電器の推奨、信頼性を示す情報の評価、検索範囲の確認に関するガイドです。プラグイン、npm、Docker、MCPB のインストールにも同梱されています。

すべてのステーションデータにはツールからもアクセスできます。ステーションのデータセット（約 20 万か所、地理的な範囲で絞り込み）は一覧表示可能なリソースとして公開されておらず、参照データはリソースではなく openchargemap_lookup_reference から提供されます。

機能リファレンス

openchargemap_find_stations _tool

• 半径検索（latitude + longitude + distance、distanceUnit は KM または Miles、最大 500）または boundingbox を指定します。1 回の呼び出しにつき、いずれか 1 つの方式のみ使用できます。任意で countrycode（ISO 3166-1 alpha-2）と、フィルター connectiontypeid、minpowerkw、operatorid、usagetypeid、levelid、statustypeid、minchargepoints を指定できます（ID フィルターには、openchargemap_lookup_reference で解決した整数 ID を 1 つ、または OR 条件で照合する配列を指定します）。
• maxresults はページの上限を設定します（デフォルト 25、最大 200）。offset は検索ごとに最大 500 件の候補を含む固定キャッシュプールをページ分割します。501 件目のレコードは上流に残りがあることを検出するためだけに使われます。この目印がない場合、totalCount は正確な値を示し、ある場合は下限を示します。どちらのケースかは notice に記載されます。
• 一致する結果がない場合は、検索の再試行方法に関する案内を含む、正常な空のリストが返されます。不明な国コードは適用されず、概要と通知にその旨が記載されます。検索範囲がない場合、中心座標の片方だけが指定されている場合、または boundingbox と座標を併用した場合は invalid_location、認証に失敗した場合は auth_failed、上流サービスが利用できない場合は upstream_unavailable で失敗します。

---

openchargemap_get_station _tool

• 数値の OCM id で指定した 1 つのステーションの全レコードを返します。すべての接続口、運営事業者／ネットワーク、利用方法とアクセスルール、充電ポイント数、利用料金、データプロバイダー、メディア、dateLastVerified が含まれます。includeComments を指定すると、すべてのチェックインがページ分割されずにインラインで追加されます。コメントの多いステーションには openchargemap_get_station_comments を使用してください。
• reliabilityNote は、観測可能な事実（検証からの経過期間、登録状況、稼働状態のフラグ、問題報告と肯定的なチェックインの比率）から算出される通常の文章です。特記事項がない場合は省略されます。not_found、auth_failed、または upstream_unavailable で失敗します。

---

openchargemap_lookup_reference _tool

• 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 _tool

• 数値の OCM id で指定した 1 つのステーションのチェックインを、新しい順に返します。それぞれに評価、日付、記録された結果が含まれます。maxresults はページの上限を設定します（デフォルト 25、最大 100）。offset／nextOffset でページ分割できます。totalComments はステーションのコメント全件数を示し、reliabilityNote の問題発生率はその全件を対象に算出されます。
• コメントとともに、登録状況、isOperational、dateLastVerified を返します。comments: [] はエラーではありません（報告がないことは、充電器が正常に動作する証拠にはなりません）。not_found、auth_failed、または upstream_unavailable で失敗します。

---

openchargemap://station/{id} _リソース

• 数値のOCM IDで指定した1つのステーションの全レコードです。コミュニティのコメントは常に含まれます。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）により、エージェントが実際に使う名称を適切なIDに解決できます。
• ジオコーディングは意図的に委任されています。このサーバーは座標を中心に動作し、場所名の検索機能を再構築するのではなく、任意のジオコーディングMCPサーバー（例：openstreetmap サーバーの openstreetmap_search_places）と組み合わせて利用できます。
• ステーションは数値のOCM IDで指定します。openchargemap_find_stations で検索してください。OCM APIにはUUIDによる検索機能がありません。

エージェントに適した出力：

• 信頼性を主要な情報として提示します。すべてのステーションにstatus、statusTypeId、isOperational、dateLastVerifiedを含め、観測可能な事実のみから導いた平易な説明のreliabilityNoteを提供します（根拠のない信頼度スコアは生成しません）。
• 欠損情報を正直に扱います。上流データで大幅に省略されるフィールドは、「欠落は不明を意味し、ゼロやfalseを意味しない」という説明を添えて任意項目にしています。サーバーが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	正の整数で指定されたページサイズが大きすぎる場合、通知とログを出力し、openchargemap.pagination.clamps カウンターを記録して、ツールの最大値（ステーションは 200、コメント／参照データは 100）に制限します。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 instrumentation（スパン、メトリクス、完了ログ）を有効にします。	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 呼び出しはラップし、生データを検証してからドメイン型に正規化し、出力スキーマに沿って返してください。不足しているフィールドを捏造してはいけません

帰属表示とデータライセンス

充電ステーション、コネクター、運営事業者のデータは、EV充電スポットのコミュニティ運営による世界規模の登録簿である Open Charge Map から取得しています。ライセンス条件はデータプロバイダーによって異なります。提供されている場合、ステーションのレコードには dataProviderLicense と isOpenDataLicensed が含まれます。ライセンスが明記されていない場合、ライセンスは不明です。

ステーションデータ © Open Charge Map の貢献者および各ステーションに記載されたプロバイダー（openchargemap.org）。ライセンス条件はプロバイダーによって異なります。

すべてのツールレスポンスにはこの attribution 文字列が含まれ、サーバーはセッションレベルの instructions にも同じ内容を記載します。Open Charge Map、その貢献者、および各ステーションのプロバイダーへの帰属表示を維持し、再利用する前に該当プロバイダーのライセンス条件を確認してください。このサーバー自体のコードは Apache-2.0 です（下記参照）。

貢献

Issue を歓迎します。提出前にチェックとテストを実行してください。

bun run devcheck
bun run test

ライセンス

Apache-2.0 — 詳細は LICENSE を参照してください。Open Charge Map のデータには独自のライセンスが適用されます。帰属表示とデータライセンスを参照してください。