PlaceRoot

Ground AI agents in open map data.

PlaceRoot is an MCP server that answers spatial questions from Overture Maps — no API key, no signup, no vendor platform.

  • Answers, not data dumps. Every tool returns compact, ranked results sized for an agent's context window — never a raw GeoJSON dump.
  • Rich, filterable place data. Category, brand, confidence, operating status, contactability — all queryable, sourced from Overture's open dataset (contributed by Meta, Uber, TomTom, and others).
  • Boundary-accurate. Search inside a named place's real administrative polygon, not just a guessed radius circle.
  • Zero setup. Reads Overture's public data directly — nothing to install beyond the server itself, no key, no database.

Quick start

Add to Claude Desktop / Claude Code:

{
  "mcpServers": {
    "placeroot": {
      "command": "uvx",
      "args": ["placeroot"]
    }
  }
}

(npx placeroot also works, if you'd rather use the npm launcher: set "command": "npx".)

Or run it directly:

uvx placeroot             # stdio MCP server
uvx placeroot --http      # HTTP endpoint at http://127.0.0.1:8321/mcp

What it can do

20 tools, all returning compact, budgeted answers. Several single-item tools have a *_batch sibling that collapses many calls into one round-trip.

Tool Answers
find_places Named places near a point or inside a named area / division polygon, nearest first — filter by category, brand, confidence, operating status, or has-website / has-phone
summarize_area What's in an area: total places and top categories
compare_areas 2–5 areas side by side: category mix, density, and what differs most
within_distance Is the nearest matching place within N meters of a point?
distance_matrix Straight-line distances between many origins and destinations at once
place_details One place in full: addresses, contacts, brand, sources, confidence
admin_lookup The admin hierarchy containing a point: neighborhood up to country
summarize_buildings Building stock in an area: count, footprint area, height and use mix
buildings_at Nearest building footprints to a point
geocode Free-text place name → ranked candidates with coordinates and admin context (geocode_batch for many at once)
resolve_place Free-text place reference → stable ids an agent can hold onto across turns (resolve_place_batch)
reverse_geocode Point → nearest address plus its containing admin areas (reverse_geocode_batch)
search_categories Free text → the right Overture category slug to filter find_places by
isochrone The area reachable within N minutes on foot, bike, or car
render_map Any result → a self-contained interactive HTML map
simplify_geometry Any geometry → simplified to fit a token budget
data_version Which Overture release the answers are drawn from

Why

Agents are bad at maps. Existing map tools either require vendor API keys or return payloads far too large for a context window. PlaceRoot's rule: every answer fits in a couple of thousand tokens, and anything bigger comes back as a summary.

A few things that set it apart:

  • Stable place ids. Every place carries its Overture GERS id, so an agent can hold onto a place across turns and look it up again later instead of re-searching.
  • Built-in geocoding. Place-name lookup works out of the box — no third-party geocoding service involved.
  • Fast repeat queries. Frequently used data is cached locally, so repeat questions answer in milliseconds and keep working offline.
  • Self-hostable end to end. Run it locally, serve it over HTTP, or point it at your own copy of the data — no dependency on anyone else's service.

Development

uv sync           # install dev dependencies
uv run pytest     # offline test suite
uv run ruff check .

Docs

License

MIT

Project links

Key dates

PyPI data
Data sourced directly from PyPI's database.
  • Released:
Newer release available (0.8.0)

1 maintainer

PyPI data
Data sourced directly from PyPI's database.
Avatar for chuofringer from gravatar.com chuofringer

Credits

Author: Vibe Mapper

License expression

MIT
View SPDX License List

Requires

Python >=3.11

Tags

ai-agents duckdb geospatial mcp openstreetmap overture-maps

Classifiers

Report project as malware

Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Source Distribution

placeroot-0.4.1.tar.gz (715.8 kB view details)

Uploaded Source

Built Distribution

If you're not sure about the file name format, learn more about wheel file names.

placeroot-0.4.1-py3-none-any.whl (141.1 kB view details)

Uploaded Python 3

File details

Details for the file placeroot-0.4.1.tar.gz.

File metadata

  • Download URL: placeroot-0.4.1.tar.gz
  • Upload date:
  • Size: 715.8 kB
  • Tags: Source
  • Uploaded using Trusted Publishing? Yes
  • Uploaded via: twine/7.0.0 CPython/3.13.14

File hashes

Hashes for placeroot-0.4.1.tar.gz
Algorithm Hash digest
SHA256 ee5c25d9bd1258ce0c66bc6f4cd81cc4f3e5164aa0fb7ffe2284af5a83248345
MD5 f22eec80d5a6da0ab92c73f48a5f1fc7
BLAKE2b-256 b8812cbf693bbb9b3ab244886d719cf75e0797b5aec87904d0247c6aac54a66b

See more details on using hashes here.

Provenance

The following attestation bundles were made for placeroot-0.4.1.tar.gz:

Publisher: release.yml on chuofringer/placeroot

Attestations: Values shown here reflect the state when the release was signed and may no longer be current.

File details

Details for the file placeroot-0.4.1-py3-none-any.whl.

File metadata

  • Download URL: placeroot-0.4.1-py3-none-any.whl
  • Upload date:
  • Size: 141.1 kB
  • Tags: Python 3
  • Uploaded using Trusted Publishing? Yes
  • Uploaded via: twine/7.0.0 CPython/3.13.14

File hashes

Hashes for placeroot-0.4.1-py3-none-any.whl
Algorithm Hash digest
SHA256 11f3d1c736c19838a93a89f07b0358e2159b20f21327a01296756127f85437f8
MD5 574969f83587fdb73029234521eb94cb
BLAKE2b-256 012d5c1ec75974ff1f77f9ff4dd05c227c13ffd4bab89e1efc55fa3899c39d00

See more details on using hashes here.

Provenance

The following attestation bundles were made for placeroot-0.4.1-py3-none-any.whl:

Publisher: release.yml on chuofringer/placeroot

Attestations: Values shown here reflect the state when the release was signed and may no longer be current.

Supported by

AWS Cloud computing and Security Sponsor Datadog Monitoring Depot Continuous Integration Fastly CDN Google Download Analytics Pingdom Monitoring Sentry Error logging StatusPage Status page