Ultimaps

@ultimaps/mcp

Ultimaps 用の MCP サーバーです。Claude、Codex、または任意の MCP クライアントに地図を依頼すると、会話に画像が返されます。貼り付けた数値からの階級区分図、カテゴリーマップ、ピンを立てた位置を、国、州、県、郡、大陸、世界を対象に作成できます。

「米国の州を人口で色分けしてください。」 · 「EU 加盟国を通貨別に色分けしてください。」 · 「次の失業率を使って、フランスの地域を表示してください：…」 · 「ヨーロッパの地図に、当社の5つのオフィスをピンで表示してください。」

アカウントは不要です。API キーがない場合、サーバーはキー不要の利用枠を使います。プランの利用枠や、より大きなサイズまたはブランド表示なしの出力を利用するには、ULTIMAPS_API_KEY を設定してください。

ローカルコマンドを実行できませんか？ ChatGPT（開発者モード）、claude.ai、またはリモート MCP サーバーに接続するクライアントでは、代わりにホスト型サーバー https://api.ultimaps.com/mcp を追加してください。ChatGPT では、地図を使いたい各会話で有効にしてください。ツールは同じ3つで、インストールは不要です。ホスト型サーバーをご覧ください。このパッケージはローカル版です。リクエストはご自身の IP アドレスとキーを使って送信され、画像はすべてご自身のコンピューター上のファイルに保存されます。

ツール

ツール	機能
render_map	地図を画像としてレンダリングします（PNG、または Pro キーがある場合は SVG）。サイズが十分小さい場合は、インラインで表示されます。階級区分図（数値）、カテゴリー（ラベル）、または明示的な色を指定でき、ピン、タイトル、独自の見出しを付けた凡例、テーマ、地域ラベル（名前、値、または両方）、追加レイヤーも設定できます。地域名はあいまい一致で照合され、修正内容や見つからなかった項目は候補とともに報告されます。dryRun: true を指定すると、レンダリングせずに照合結果と配色案をプレビューできます。
list_maps	地図カタログです：{id, title, regionType, layers, regionCount, labels}。query で検索できます。
get_map_regions	地図ごとの地域キーとタイトルを返します。1ページあたり200件で、キー、タイトル、または別名で検索できます。

3つのツールはすべて読み取り専用です。エージェントが地図の検索ツールを使うことはほとんどありません。render_map では地域名、コード、別名を直接指定できます。

インストール

Node.js 20 以降が必要です。

Claude Code

claude mcp add ultimaps -- npx -y @ultimaps/mcp
# with a key:
claude mcp add ultimaps --env ULTIMAPS_API_KEY=um_live_… -- npx -y @ultimaps/mcp

Codex

codex mcp add ultimaps -- npx -y @ultimaps/mcp
# with a key:
codex mcp add ultimaps --env ULTIMAPS_API_KEY=um_live_… -- npx -y @ultimaps/mcp

Codex は以下の JSON ではなく TOML を使用します。~/.codex/config.toml（または信頼済みプロジェクト内の .codex/config.toml）に記述する同等の設定は次のとおりです：

[mcp_servers.ultimaps]
command = "npx"
args = ["-y", "@ultimaps/mcp"]

Claude Desktop

最新リリースから ultimaps-<version>.mcpb をダウンロードして開いてください。Claude Desktop がワンクリックでインストールし、任意の API キーを尋ねます。または、claude_desktop_config.json に以下を追加してください：

{
  "mcpServers": {
    "ultimaps": {
      "command": "npx",
      "args": ["-y", "@ultimaps/mcp"],
      "env": { "ULTIMAPS_API_KEY": "" }
    }
  }
}

Cursor

~/.cursor/mcp.json（またはプロジェクト内の .cursor/mcp.json）：

{
  "mcpServers": {
    "ultimaps": { "command": "npx", "args": ["-y", "@ultimaps/mcp"] }
  }
}

VS Code

.vscode/mcp.json：

{
  "servers": {
    "ultimaps": { "type": "stdio", "command": "npx", "args": ["-y", "@ultimaps/mcp"] }
  }
}

ホスト型サーバー

ホスト型サーバーを使うために、このパッケージは不要です。URL をクライアントに追加してください：

claude mcp add --transport http ultimaps https://api.ultimaps.com/mcp
# with a key:
claude mcp add --transport http ultimaps https://api.ultimaps.com/mcp \
  --header "Authorization: Bearer um_live_…"

設定ファイルを使うクライアントでは、たとえば ~/.cursor/mcp.json に URL のみを指定します：

{
  "mcpServers": {
    "ultimaps": { "url": "https://api.ultimaps.com/mcp" }
  }
}

ホスト型サーバーでは、キーは ULTIMAPS_API_KEY ではなく Authorization ヘッダーとして送信します。ChatGPT と claude.ai ではヘッダーを設定できないため、そこでのレンダリングには匿名利用枠が適用されます。PNG は最大1600 px、帰属表示ありで、1会話あたり1時間に最大30回までです。レンダリングごとに、30日後に期限切れとなる画像リンクも返されます。会話に表示するには大きすぎる画像と、すべての SVG はリンクのみで返されます。ChatGPT はツールから返された画像を表示しないため、そこで地図を見るにはリンクを使います。

設定

変数	デフォルト	用途
ULTIMAPS_API_KEY	なし（キー不要）	Studio → Workspace → API で取得する API キーです。無効なキーはエラーとなり、キー不要の利用枠にフォールバックすることはありません。
ULTIMAPS_API_URL	https://api.ultimaps.com	開発中にローカル API（http://localhost:3001）を指定します。通常の http が許可されるのは localhost のみです。

制限

	キーなし	無料キー	Pro キー
レンダリング	30 回/時間、5 回/分	500 回/月、50 回/日、10 回/分	5,000 回/月、1,000 回/日、30 回/分
出力	最大 1600 px の PNG、帰属表示あり	スケール 2（3200 px のラスター画像）で最大 1600 px の PNG、帰属表示あり	スケール 4 で最大 4000 px の PNG、SVG、帰属表示なし

ワークスペース内のすべてのキーで月間クォータを共有します。日次と分単位の上限はキーごとに設定されるため、無料キーでは月間クォータを使い切るずっと前に、1 日あたり 50 回の上限に達します。

ドライランでは月間クォータを消費しませんが、レート制限にはカウントされます。キーなしで残りのレンダリング回数が 5 回以下になると、結果にその旨が表示されます。

レンダリング結果

• 画像：サイズが十分に小さい場合はインラインで返されます（PNG は 781 KB、SVG は 98 KB）。幅のデフォルト値である 1200 px なら、通常はこのサイズに収まります。すべてのレンダリング結果は <tmpdir>/ultimaps-mcp/ にも書き込まれ、そのパスが結果に含まれるため、ターミナルクライアントでは実際に開けるファイルを取得できます。お客様に代わって再レンダリングや再サンプリングを行うことはありません。
• テキストレポート：自動修正された地域キーと一致しなかった地域キー、および候補、解決されたコロプレスマップの設定、警告（layer_unavailable や labels_overlap など）、マップを編集するために Ultimaps Studio で開くリンク、サポート用のレンダリング ID が含まれます。
• 埋め込み可能な画像 URL：キーなしの PNG レンダリングで、仕様全体が約 2,000 文字の URL に収まる場合に提供されます。そのため、小規模なデータセットに限られます。この URL に含まれるのは画像ではなく仕様で、キーなしでレンダリングされるため、キーが設定されている場合は提供されません。
• structuredContent：ツールの outputSchema で定義された、同じレポートのデータ形式です。

プライバシーポリシー

このサーバーはお使いのマシン上で実行され、独自のテレメトリーはなく、Ultimaps API（https://api.ultimaps.com または設定した ULTIMAPS_API_URL）とのみ通信します。Ultimaps のプライバシーポリシー全文は、ultimaps.com/privacy-policy をご覧ください。

Ultimaps に送信される情報。 ツール呼び出しは Ultimaps API への通常の HTTPS リクエストであるため、お使いの IP アドレスと ultimaps-mcp/<version> のユーザーエージェントが送信されます。render_map はマップリクエスト全体（地域キーと値、ピン、タイトル、スタイル設定）を送信します。ULTIMAPS_API_KEY を設定した場合、このキーはレンダリングリクエストでのみ送信されます。

Ultimaps が保持する情報。 各レンダリングリクエストはログに記録されます。記録される情報は、リクエストの内容、マップと結果、処理時間、お使いの IP アドレスとユーザーエージェント、キーを使ったリクエストの場合は使用されたキーとワークスペースです。これにより、サポートがレンダリング ID を使って記録を検索できるほか、「Open in Studio」リンクでマップを再構築し、使用状況を集計できます。リクエストの内容は 30 日間、IP アドレスとユーザーエージェントは 90 日間保持されます。その後に残るのは使用記録で、キーを使った場合はワークスペースに紐付けられます。Ultimaps は、失敗したリクエストの詳細を受け取る可能性のある、サードパーティのエラー監視サービスを使用しています。Ultimaps はこのデータを販売したり、広告に使用したりしません。

お使いのマシンに保存される情報。 レンダリングされた画像はすべて <tmpdir>/ultimaps-mcp/ に書き込まれ、このサーバーが削除することはありません。会話内のツール結果など、MCP クライアントが保持する情報には、そのクライアント独自のプライバシーポリシーが適用されます。

共有可能なリンク。 キーなしの小規模なレンダリングで提供される埋め込み可能な画像 URL には、マップリクエスト全体が含まれます。このリンクを持つ人は誰でも、その内容を確認できます。

ホスト型サーバー。 https://api.ultimaps.com/mcp のサーバーはお客様のマシンではなく Ultimaps のサーバー上で実行されるため、上記のお客様のマシンに関する説明は当てはまりません。プライバシーポリシー全文は、このサーバーにも適用されます。

ご質問や削除のご依頼は、レンダリング ID を添えて [email protected] までお問い合わせください。

開発

npm install
npm run typecheck
npm test           # unit + in-process protocol tests
npm run build      # → dist/

実際の API を使用し、stdio 経由でエンドツーエンドテストを実行します（お使いのプランのレンダリングユニットを消費します）。

npm run build
node scripts/smoke.mjs

src/generated/render-request.schema.json は Ultimaps API コントラクトから生成されます。手動で編集しないでください。ツールとプロパティの説明は src/descriptions.ts にあります。引数はローカルでは検証されません。API は追加のみを許可し、400 レスポンスには候補が含まれます。

Issue やプルリクエストを歓迎します。リリースは Ultimaps チームが作成し、採用された変更は次のリリースに含まれます。

このパッケージが公開するのは bin のみです。import '@ultimaps/mcp' は サポートされておらず、dist/index.js の読み込み時に stdio サーバーが起動するため、 モジュール名の解決に失敗します。

ライセンス

MIT © Ultimaps。LICENSE をご覧ください。