Skip to main content
Glama
overture-maps

overture-maps

by koizumikento

overture-maps-mcp

Overture Mapsの6テーマを検索・分析する、Pythonライブラリ・CLI・読み取り専用MCPサーバーです。公式Overture製品ではなく、独立した実装です。

Python 3.12以上、uv、DuckDBを使用し、MCP接続には任意依存の公式MCP Python SDKを使います。住所から座標を得る処理はgeo-jp-mcp等へ任せ、座標・検索範囲・地物IDを渡して組み合わせます。

Pythonライブラリ・CLI

通常のインストールにはMCP SDKを含みません。MCPサーバーを使う場合だけ[mcp]を追加します。PyPIには未公開のため、取得したこのリポジトリからインストールしてください。

uv add C:/workspace/overture-maps-mcp       # 他のPythonプロジェクトの依存へ追加
uv tool install C:/workspace/overture-maps-mcp  # CLIとしてインストール
overture-maps --help
overture-maps search --theme places --type place --bounds 139.760 35.680 139.762 35.682 --limit 2
from overture_maps_mcp import Client, Bounds

client = Client()
result = client.search(
    "places",
    "place",
    bounds=Bounds(west=139.760, south=35.680, east=139.762, north=35.682),
    limit=2,
)
print(result.data)
print(client.storage_dir)

Python、CLI、MCPで同じ9種類の操作を使えます。引数の型と検証ルールは共通です。結果と出典の形式、JSONファイルや標準入力からの指定方法、エラー、保存先はライブラリ・CLIガイドを参照してください。

依存関係を専用の保存先にまとめてCLIを使うには、リポジトリで次のコマンドを実行します。

Windows:

./manage.ps1 cli search --theme places --type place --bounds 139.760 35.680 139.762 35.682 --limit 2

Windows以外:

uv run --isolated --no-project --no-cache --python 3.12 python -B manage.py cli search --theme places --type place --bounds 139.760 35.680 139.762 35.682 --limit 2

Related MCP server: geolibre-mcp

インストール・起動

git clone https://github.com/koizumikento/overture-maps-mcp.git
cd overture-maps-mcp
.\manage.ps1 run

初回は依存をインストールします。Windows以外ではuv run --isolated --no-project --no-cache --python 3.12 python -B manage.py run。管理用Pythonは一時環境で動かし、MCP本体の実行環境を後から削除できるようにしています。

stdioが既定です。ローカルMCPクライアントからの設定例:

{
  "mcpServers": {
    "overture-maps": {
      "command": "uv",
      "args": ["run", "--isolated", "--no-project", "--no-cache", "--python", "3.12", "python", "-B", "C:/workspace/overture-maps-mcp/manage.py", "run"]
    }
  }
}

Streamable HTTPは.\manage.ps1 run -Transport streamable-http、接続先はhttp://127.0.0.1:8000/mcpです。-Portでポートを変更できます。通常のHTTP起動はloopback専用・認証なしです。

Sites向けには認証backend+Worker adapterの手順を用意しています。DuckDBは別Pythonホストで実行し、-SitesBackendでサービス認証付きのstateless HTTPを起動します。Sites OAuthとユーザー認可はWorker側で扱います。Python API・CLI・stdioの9操作は共通で、Sites単体では実行しません。

Workerの /mcp は、Origin ヘッダーがないリクエストと、Sitesと同じオリジンからのリクエストを受け付けます。別のオリジンからのリクエストには、バックエンドに接続せずHTTP 403を返します。

TLS証明書と実行環境の更新

カタログとSTACの取得に使うHTTPXは、certifi>=2026.10.19 のCAバンドルで証明書を検証します。certifiのセキュリティ勧告

実行環境の依存関係を更新するときは、MCPを停止し、次のコマンドを実行してから再起動してください。

  • Windows: ./manage.ps1 setup

  • Windows以外: uv run --isolated --no-project --no-cache --python 3.12 python -B manage.py setup

開発環境ではそれぞれ setup -Dev、setup --dev を使います。wheelやローカルパスからインストールした場合は、インストール先の環境でパッケージを更新してください。

Python本体、pip、uv、OS、DuckDBの通信で使う証明書の更新は、利用環境ごとに別途確認してください。既存の仮想環境も確認の対象です。TLS検証を無効にしないでください。Python公式の案内

PCの保存容量と削除

管理コマンド経由の起動では、Python依存・uvキャッシュ・DuckDB拡張・Python bytecodeをリポジトリ内の.runtimeへ集約します。地理データの永続DBやディスクキャッシュは作りません。起動時に現在の保存容量をstderrへ表示します。

.\manage.ps1 storage   # 保存先・内訳・旧保存先・対象外の共有拡張のサイズを表示
.\manage.ps1 clean     # MCPを止めてから、専用環境・キャッシュ・拡張を削除

cleanはソース・docs・Gitを保持し、.runtimeと旧版のリポジトリ内.venv・.cache・dist・既知のテストキャッシュ・bytecodeを削除します。稼働中のMCPがあれば拒否し、所有マーカーがない保存先や想定外のファイル、外部へのリンクも拒否します。再度runすれば依存・拡張を再取得できます。サイズはbytes / MiBとファイル数で表示し、物理占有量とは異なる場合があります。

ファイルを削除するには、MCP設定を外してサーバーを停止してから、clean を実行します。削除対象の環境に依存しないよう、Windowsでは上記のPowerShellコマンドを使ってください。Windows以外では次のコマンドを使います。

uv run --isolated --no-project --no-cache --python 3.12 python -B manage.py clean

uv本体、共有Python、ユーザーホームの .duckdb/extensions は削除対象外です。このMCPが取得するDuckDB拡張は .runtime 内に保存し、共有拡張の容量は別に表示します。管理用の .runtime.lock(1 byte)はリポジトリに残ります。保存量は依存関係や拡張のバージョンによって変わります。固定の容量上限はありません。

Tools

Tool

用途

overture_catalog

最新・利用可能リリース、6テーマとタイプ、上限の確認

overture_schema

選択データの列・型の確認

overture_search

矩形・半径・ポリゴンと属性条件で検索、全属性/選択属性、ページング、GeoJSON

overture_get_feature

UUIDの詳細取得。範囲を省略すると現在のGERSで解決

overture_summarize

検索と同条件で全件数・複数属性別集計・数値統計・面積・道路長・距離

overture_nearest

最大半径内の近傍検索。距離とIDによる順序・ページング

overture_spatial_join

2テーマ/タイプの交差・包含・接触・重複・距離条件。ペア/全件数/左地物別件数

overture_compare_releases

2リリースを同じ条件で比較、追加・削除・変更・不変の件数と詳細

overture_resolve_id

位置・テーマ不明のUUIDをGERSで解決。現存・削除・未収録を区別

6テーマ: addresses, base, buildings, divisions, places, transportation。タイプの組み合わせはcatalogが返します。地図描画・住所文字列のgeocoding・経路探索は担当しません。これらを必要とするクライアントは別のMCPと組み合わせてください。

使い方:

  1. overture_catalogでreleaseとtheme/typeを取得する。

  2. 必要ならoverture_schemaでフィルタ・集計列を確認する。

  3. 同じreleaseを指定してsearch/get_feature/summarizeを呼ぶ。

{
  "theme": "places", "feature_type": "place",
  "bounds": {"west": 139.74, "south": 35.67, "east": 139.78, "north": 35.70},
  "category": "cafe", "limit": 20,
  "release": "2026-09-23.1"
}

例にあるリリースは指定方法を示すものです。公開データの保持期間は最大60日なので、検索には overture_catalog が返すリリースを使ってください。施設の分類は taxonomy.primary で絞り込めます。名前は大文字・小文字を区別せず、部分一致で検索します。存在しない列を条件に指定するとエラーになります。

属性は既定で全列を返します。必要な列だけ取得するには fields を指定します。filters では型に応じた20種類の条件を使え、構造体や配列に含まれる属性も指定できます。範囲検索、集計、空間結合、リリース間の比較の例は検索・分析ガイドを参照してください。

結果・上限

  • 結果には対象の release、theme、feature_type、scope が含まれます。出典と利用条件は source、license、attribution_url で確認できます。取得したデータ、次ページの位置、警告はそれぞれ data、next_cursor、warnings で返ります。

  • WGS84の矩形範囲は東西・南北1度以内、概算2500km²以内。日付変更線をまたぐ範囲は分割します。

  • 1ページ最大50件。次ページではrelease・範囲・フィルタ・geometry設定を維持します。

  • bboxで候補を絞り、geometryとの交差・距離条件で地物を選びます。件数はレコード数。面積・線の長さは別の指標で、WGS84楕円体のm² / mです。

  • 集計の上位50グループを返し、other_countで省略分を示します。検索ページの件数を全件数として扱いません。

  • geometryは検索では既定で省略。詳細取得で確認できます。dataは最大400KB、超過時は件数・範囲・geometry設定の変更を促すエラーになります。

  • DuckDBの実行は1回30秒、メモリ512MB、同時2本に制限。巨大な全世界検索・任意SQL・任意URL/パスはtoolへ公開しません。

  • 初回のDuckDB spatial / httpfs拡張取得と公開データ問い合わせにはネットワークが必要です。処理はローカルで実行し、AWSの認証情報は不要です。

  • 半径は最大25000m、polygonは最大2000座標。空間結合・版比較は各データセット最大5000候補で、超過時は範囲や条件を絞るエラーを返します。

  • 点以外の距離は局所投影による近似、円の面積・長さのクリップは128辺の近似です。GERSレジストリは現在版のみ、履歴版・非GERSのID取得にはboundsが必要です。

  • 公式STACのファイル収録範囲で問い合わせ先を絞り、メタデータを10分キャッシュします。初回は各タイプのファイル一覧を確認する時間がかかります。STAC取得失敗・上限超過は成功や空結果として扱いません。

利用条件・データ品質

コードはMIT。データの権利は別で、Overtureの出典・ライセンス一覧が正本です。PlacesにはCDLA-Permissive-2.0、Apache-2.0、CC0などが混在し、Base・Buildings・Divisions・TransportationはODbL。住所は出典ごとに異なります。返却したsource・sourcesと利用条件を保持してください。

件数は当該リリース・検索範囲のレコード数です。施設の現実の網羅率、現在営業中であること、座標の正確性を保証しません。AddressesはAlpha。Base・building_partのIDにはGERS安定性保証がありません。IDが同じであることとリリース間の完全追跡は別です。

開発・検証

.\manage.ps1 setup -Dev
$env:UV_PROJECT_ENVIRONMENT = "$PWD/.runtime/venv"
$env:UV_CACHE_DIR = "$PWD/.runtime/uv-cache"
$env:PYTHONPYCACHEPREFIX = "$PWD/.runtime/pycache"
$env:OVERTURE_MAPS_MCP_STORAGE_DIR = "$PWD/.runtime"
uv run python -c "import duckdb; from overture_maps_mcp.storage import Storage; duckdb.connect(config={'extension_directory': str(Storage.default().extension_directory())}).execute('INSTALL spatial')"
uv run ruff check .
uv run ruff format --check .
uv run ty check .
uv run pytest
node --test sites/tests/worker.test.mjs
node sites/scripts/build.mjs
uv build

ローカルの合成Parquet fixtureによるSQL・geometry・ページング・集計検証とMCP接続試験を既定にします。公開データの問い合わせや実クライアント接続の結果はvalidationで別に記録します。

公開データに接続して確認する場合は、目的に応じて次のコマンドを実行します。これらの確認は通常のpytestには含まれません。

  • uv run python scripts/verify_managed.py で、管理コマンド経由のstdio接続、施設検索、稼働中に削除を拒否する動作を確認します。

  • uv run python scripts/verify_live.py で、stdio接続から6テーマを確認します。

  • uv run python scripts/verify_http.py で、ループバックのHTTP接続とカタログ取得を確認します。

uv run python scripts/verify_complete.py は、全15タイプについて、公式の列定義と取得結果、条件付きの件数、地物の詳細を公開データで照合します。空間検索、計測、結合、ID解決、リリース間の比較も確認します。地理データはディスクに保存しません。この検証の対象はツールの動作です。

設計・受入条件: requirements。参考: PlaceRoot、Overture Maps MCP Server、Soapbox MCP。これらの機能分割を参考にし、コードは複製していません。

Available Tools

9 tools
overture_catalogB
Read-onlyIdempotent

Discover all six themes/types and available releases. Pin a release for later calls.

Use before searching; does not query geographic features or resolve an address.

Inputs: no named parameters. Returns: Bounded, provenance-bearing structured result shared by the tools.

overture_compare_releasesA
Read-onlyIdempotent

Compare two available release snapshots by ID in the same area and filters.

    Returns exact added/removed/modified/unchanged counts and paginated changes, including
    before/after properties and schema changes. Compares all properties regardless of
    fields selection, plus topological geometry equality. <=5000 records per snapshot.
    Added/removed can mean crossing scope/filters; not global creation/deletion. IDs in
    Addresses/Base/building_part lack GERS stability. Use catalog for available releases.
    

Inputs: after (required), theme (required), before (required), bounds (required), +6 more. Returns: Bounded, provenance-bearing structured result shared by the tools.

overture_get_featureA
Read-onlyIdempotent

Get a UUID feature from search with its known bounding area and pinned release.

With bounds, lookup is pinned to that area/release. Without bounds, uses the current GERS registry and its verified shard, and requires the matching theme/type/current release. Non-GERS types and historical releases need bounds. Empty scoped results do not establish global nonexistence. fields chooses properties; default is all.

Inputs: theme (required), identifier (required), feature_type (required), bounds, +3 more. Returns: Bounded, provenance-bearing structured result shared by the tools.

overture_nearestA
Read-onlyIdempotent

Find the nearest intersecting features within a maximum radius; distance in meters.

Searches points, lines and polygons; polygon containing center has zero distance. Stable order is distance then ID. Point distances are geodesic; line/polygon edges use a local azimuthal-equidistant projection. Empty means none within the radius.

Inputs: theme (required), center (required), radius_m (required), feature_type (required), +6 more. Returns: Bounded, provenance-bearing structured result shared by the tools.

overture_resolve_idA
Read-onlyIdempotent

Resolve a UUID without knowing its theme or position using the current GERS registry.

    Returns live feature and verified file, removed ID metadata, or not_in_registry.
    Registry is unversioned and excludes Addresses/Base/building_part. For those IDs or
    historical releases use overture_get_feature with known bounds. Never infer global
    nonexistence from not_in_registry. Default returns all properties and geometry.
    

Inputs: identifier (required), fields, include_geometry. Returns: Bounded, provenance-bearing structured result shared by the tools.

overture_schemaA
Read-onlyIdempotent

Inspect dataset columns for a theme/type before filtering or grouping.

    Use with a pair from overture_catalog; reads Parquet metadata, not feature rows.
    

Inputs: theme (required), feature_type (required), release. Returns: Bounded, provenance-bearing structured result shared by the tools.

overture_spatial_joinA
Read-onlyIdempotent

Relate features across themes/types in one release and bounded area.

    Relation is left-to-right: places within division_area, or areas containing places.
    Both datasets are scoped to bounds; <=5000 candidates each or fail without partial
    analysis. pairs paginates pairs with properties/provenance; count returns total pairs;
    group_left returns every left ID with match count, including zero. within_distance
    needs distance_m and uses a local projected minimum geometry distance in meters.
    

Inputs: left (required), right (required), bounds (required), mode, +5 more. Returns: Bounded, provenance-bearing structured result shared by the tools.

overture_summarizeA
Read-onlyIdempotent

Count all dataset features intersecting a bounded area, optionally group by a column.

    Accepts exactly the same area/attribute conditions as search. Group by up to 3 scalar
    property paths; top 50 groups with other_count. Aggregate sum/avg/min/max/count/
    count_distinct of properties or @area_m2/@length_m/@distance_m (needs center).
    Geometry metrics default to clipped scope; circles use a 128-segment clip polygon.
    Counts and property aggregates are over whole intersecting records, not prorated.
    

Inputs: theme (required), feature_type (required), name, bounds, +11 more. Returns: Bounded, provenance-bearing structured result shared by the tools.

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    TDQS

    A3.9/5.0

    Scored across 9 tools

    Disambiguation4/5

    Most tools have clearly distinct purposes (catalog vs schema vs summarize vs spatial_join vs compare_releases). However, overture_get_feature and overture_resolve_id both retrieve a feature by UUID, and overture_search vs overture_nearest both find intersecting features, so a couple of boundaries rely on descriptions rather than being inherently separate.

    Naming Consistency4/5

    All tools share a consistent overture_ snake_case prefix with predictable verb/verb_noun forms (search, get_feature, summarize, spatial_join, compare_releases, resolve_id). Minor deviation: catalog and schema are noun-style rather than action verbs, but the overall pattern is readable and uniform.

    Tool Count5/5

    Nine tools is well-scoped for a rich geospatial dataset, with each tool covering a distinct capability (discovery, schema, search, nearest, retrieval, aggregation, joins, release diffing). No redundant or filler tools.

    Completeness5/5

    The surface covers the full read-only query lifecycle: theme/release discovery, schema inspection, spatial and attribute search, distance search, feature retrieval, aggregation, cross-theme joins, release comparison, and ID resolution. No obvious gaps remain for a read-only dataset domain.

    Maintenance

    ActivityMaintained
    ResponsivenessNo recent community issues

    Related MCP Connectors

    Related MCP Servers

    • A
      license
      Not graded
      quality
      D
      maintenance
      Enables natural language and geospatial queries on PostGIS databases, with 32 tools for spatial analysis, geometry operations, and database management.
      5
      MIT
    • A
      license
      Not graded
      quality
      D
      maintenance
      Provides geospatial data intelligence tools for inspecting, querying, and converting geospatial data using DuckDB Spatial.
      1
      MIT
    • F
      license
      B
      quality
      D
      maintenance
      Provides read-only query tools over OpenStreetMap data in PostGIS, enabling natural language queries for features, categories, and spatial analysis.
      7
      -
    • A
      license
      A
      quality
      B
      maintenance
      Read-only access to a self-hosted GeoLens geospatial catalog: dataset search, schemas, GeoJSON features, saved maps, and sandboxed read-only SQL over PostGIS.
      9
      302
      Apache 2.0