maproll

@maproll/mcp

AI アシスタントが実際の地図を作成できるようにします。作成した地図はすべて maproll URL として返されます。恒久的に利用でき、埋め込み可能で、次の変更にも使えます。

この画像は、このリポジトリ内のファイルではありません。maproll URL がリアルタイムで描画したものです。これこそがこの仕組みの要点です。URL が地図そのものです。

インストール

claude mcp add maproll -- npx -y @maproll/mcp

ほかのクライアントでも、同じコマンドを設定として使います。Claude Desktop、Cursor（.cursor/mcp.json）、VS Code（"servers" 配下の .vscode/mcp.json）の場合は次のとおりです。

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

Node 20 以降が必要です。API キー、サインアップ、アカウントは不要です。サーバーは必要に応じて npm から実行され、公開レンダリング API と通信します。

試してみる

次のような言い方で、アシスタントに頼んでみてください。

1人あたりのコーヒー消費量が最も多い10か国を地図にしてください。

明るい地図で、EU 加盟国を強調してください。

上海からロッテルダムまでの海路を、港を示して描いてください。

暗い地図で、NATO と BRICS の加盟国を比較し、埋め込み用の URL を教えてください。

1つだけ試すなら、3つ目がおすすめです。海路はアジアを横切る直線ではなく、スエズ、パナマ、マラッカを通ります。

ツール

create_map

データから地図を作成します。数値はコロプレス図になり、色は地域を単色で塗り、テキスト値は定性的な区分を示します。highlight は、対象が「どれだけ」ではなく「どの」地域かを示す場合に使います。

地域 ID は、世界スコープでは ISO 3166-1 alpha-2（US、DE、BR）、国スコープでは ISO 3166-2（RO-B、RO-CJ）です。データは構造化された状態で渡されます。URL の文法はサーバーが管理するため、モデルが US:200:#ff0000 を手作業で組み立てる必要はありません。

add_layers

すでに作成した地図に、マーカー、ルート、比例円、パターン塗り、注釈、ラベルを追加します。地図の URL を受け取り、そこに追加します。そのため、毎回最初から作り直すのではなく、複数のやり取りを通じて地図を組み立てることもできます。

find_places

地名を実際の座標と maproll が使用する ID に変換します。国、地域、都市、空港に対応し、それぞれ ISO 3166-1／3166-2／IATA コードを利用できます。

マーカーを置く前には、ぜひ使ってください。記憶に頼った座標は数度単位で間違っていることが珍しくありませんが、地図は正しいマーカーも間違ったマーカーも同じように自信たっぷりに描画します。

describe_options

レンダラーが実際に受け付けるスコープ、テーマ、マーカーアイコン、投影法、パターン塗りを確認できます。存在しないテーマ名やアイコン名を指定しても何も描画されず、エラーも報告されません。推測するより、確認するほうが確実です。

返される内容

地図を作成するすべてのツールは、表示用のレンダリング済み PNG と、次の情報を返します。

フィールド	内容
svg_url	地図です。埋め込み可能で恒久的に利用でき、ほかのツールに渡す URL です。
png_url	同じ地図の PNG です。
editor_url	maproll エディターで開きます。地図は読み込まれており、編集できます。
embed	すぐに使える <img> タグです。
warnings	致命的ではない問題です。たとえば、レンダラーが認識しなかった地域 ID などです。

URL が地図そのものである理由

エージェントが返すのは通常、ファイルや blob など、会話の中にだけ存在する成果物です。maproll が返すのはアドレスです。

prompt → assistant → maproll MCP → https://api.maproll.io/map.svg?…
                                        ↓
              README · docs · dashboard · newsletter · the next tool call

svg_url 自体が状態を表すため、セッションも保持すべき状態もありません。add_layers に渡すと、追加内容が適用された新しい URL が返されます。各手順で生成された URL はすべて、JavaScript なしで <img> タグに指定すれば、いつまでも描画されます。

ブランディングとキー

マップはアカウントなしで利用できます。匿名利用で発生するのは、ワードマークの表示です。このサーバーが作成するすべてのマップには、隅に小さな maproll のマークが付きます。

キーを使うと、マークを非表示にできます。エディターの app.maproll.io → API keys でキーを発行し、サーバーの環境変数に渡します。

{
  "mcpServers": {
    "maproll": {
      "command": "npx",
      "args": ["-y", "@maproll/mcp"],
      "env": { "MAPROLL_API_KEY": "mr_live_…" }
    }
  }
}

キーを使うと、返される URL にはそのマップだけに紐づいた署名が付きます。そのため、マップを埋め込んだページをどこで公開しても、キーそのものがコピー可能なリンクに表示されることなく、マップが正しく表示されます。知っておくべきことが 2 つあります。キーの有効期限は 90 日で、期限が切れると、そのキーを使って公開した埋め込みマップには再びワードマークが付きます。問題になる場合は、マップを再生成してください。

OpenStreetMap のクレジット表記は、どちらの場合も必要です。これはライセンス上の義務であり、ブランディングではありません。

変数	デフォルト	用途
MAPROLL_API_KEY	—	マップのレンダリングを許可し、ワードマークを非表示にします。
MAPROLL_PLACES_URL	https://mcp.maproll.io/places	find_places が地名を解決する場所です。ローカル開発の場合にのみ上書きしてください。

リソースとプロンプト

7 つの読み取り専用リソースで、モデルが通常は推測するカタログを公開します。特に重要なのが maproll://grammar で、そのほかにスコープ、テーマ、アイコン、投影法、パターンの一覧と、実例集があります。

サーバーには 3 つのプロンプトが用意されています。mapped_episode（Mapped のスタイルに沿ったデータセット）、readme_map（マップと、実際の代替テキストを含む貼り付け用スニペット）、refine_map（既存のマップを平易な英語で変更）です。

ドキュメント

• maproll.io/mcp — このサービスの概要を 1 ページで紹介しています。
• docs.maproll.io/docs/mcp/intro — クライアントごとのインストール方法、すべてのツールのスキーマ、レシピを掲載しています。
• MCP Registry に io.maproll/maproll として登録されています。

開発

構成、ローカルでの開発サイクル、エンドツーエンドのスモークテストについては、DEVELOPMENT.md を参照してください。公開手順については PUBLISHING.md を参照してください。

MIT ライセンスです。