MapsMCP

Maps that agents can understand

Comment

MapsMCP, maps that agents can understand, not just click

The problem

Maps are made for people. We look at the screen, drag it about, zoom in, spot a place, and change direction without really thinking about it.

AI agents have a rougher time. Playwright, Selenium, and Appium can click, drag, and scroll, but a map is not a normal webpage. It is a moving visual surface made from tiles, canvas layers, marker clusters, labels, animations, and changing camera positions.

The main issue, well, the awkward bit, is that a gesture has no stable meaning. Dragging 280 pixels may move one street at one zoom level and half a city at another. Screen size changes the result. Slow-loading tiles can change it again. An agent may complete the gesture and still have no reliable answer to “Where is the map now?” or “Which places can the person actually see?”

That is a poor foundation for ride hailing, food delivery, travel, field work, or emergency response.

What I built

MapsMCP is a WebMCP-powered interactive map prototype.

It keeps a normal human map experience, built with Leaflet and real OpenStreetMap tiles. People can pan, zoom, search places, inspect routes, and select destinations in the usual way.

A compatible browser agent gets structured WebMCP tools for the same map. It can inspect the current viewport, move the camera by metres, set an exact location and zoom level, find nearby places, measure distance, plan routes, and add visible shared pins.

The map is central London for the demo. The core idea works in any city.

Why this is a strong fit for WebMCP

WebMCP lets a website register structured browser-native tools for an AI agent. Each tool has a name, description, input schema, and execution function.

Maps are especially well suited to this because the map engine already knows the important information. It knows the camera centre, zoom, visible bounds, selected place, distances, pins, and routes. That semantic state is usually hidden behind the visual interface.

MapsMCP exposes the useful parts safely and clearly.

Instead of an agent attempting to drag right and hoping for the best, it can call pan_map with a compass direction and a distance in metres. Instead of guessing what is visible after a gesture, it can call get_map_viewport and receive the geographic bounds, zoom level, and visible structured places.

WebMCP turns a map from a picture an agent pokes at into a workspace it can understand.

Better experience for people and agents

For a person, MapsMCP still behaves like a map. There is no strange agent-only screen. They can explore normally, see every map movement, inspect the result, and alter the plan.

For an agent, the interaction becomes deterministic. It gets stable place IDs and geographic results, rather than an uncertain screenshot after a drag.

Together, people and agents can work from the same state. A person might pan across a city to explore. ChatGPT can then inspect that exact viewport, find suitable places nearby, fit destinations into view, plan a route, and leave a shared meeting pin.

That handoff is difficult with visual browser automation alone. It can be done with a bespoke private integration, perhaps, but WebMCP makes the capability explicit, discoverable, and browser-mediated.

A realistic demo scenario

Imagine a traveller visiting London for the first time.

They are standing near Tower Bridge, a famous bridge over the River Thames. They want to walk to Borough Market, a nearby food market, and leave a meeting point for a friend.

They ask ChatGPT:

I am near Tower Bridge, a major London landmark. Find Borough Market, measure
the walking distance, fit both places into the map view, plan a walking route,
and drop a visible pin at Borough Market called “Meet here”.

ChatGPT discovers the MapsMCP WebMCP tools. It finds the locations by stable IDs, measures the distance, moves the visible map, draws the walking route, and drops the shared pin.

The traveller sees it all happen. They can keep the plan, drag the map somewhere else, or change their mind.

Supported WebMCP tools

Tool What it does
get_map_state Reads the full shared map state, including viewport, selected place, route, staged ride, and pins.
get_map_viewport Returns exact camera centre, zoom, geographic bounds, and visible places.
get_places_in_view Lists structured places inside the current visible map area.
search_places Searches the London place catalogue and returns stable place IDs.
get_place_details Returns a place’s details and nearby suggestions without scraping a tooltip.
find_nearby_places Finds places around a known location within a real-world radius.
measure_distance Measures straight-line geographic distance between two places.
pan_map Moves the visible map by compass direction and metres.
set_map_viewport Sets exact latitude, longitude, and zoom.
zoom_map Zooms by a known number of map levels.
fit_places Frames one or more place IDs in the visible map.
focus_place Flies to and selects a place in the human interface.
plan_route Previews car, cycle, or walking routes.
clear_route Removes the visible route preview and staged ride.
drop_pin Places a named visible pin at exact coordinates.
list_pins Lists shared pins currently on the map.
remove_pin Removes a shared pin through its stable ID.
prepare_ride Stages a simulated ride quote. A person still confirms it.

How I implemented WebMCP

MapsMCP uses WebMCP’s imperative API:

await document.modelContext.registerTool({
  name: "search_places",
  description: "Search MapsMCP's structured London place catalogue.",
  inputSchema: {
    type: "object",
    properties: {
      query: { type: "string" },
      category: { type: "string" },
    },
    additionalProperties: false,
  },
  execute: async ({ query, category }) => {
    return searchPlaces(query, category);
  },
});

The app registers 18 tools through document.modelContext.registerTool(), with a compatibility fallback for older navigator.modelContext browser implementations.

Every tool calls the same React state actions used by the human interface. If an agent pans the map, the person sees the map pan. If it drops a pin, the pin appears on the real map. Registration is owned by an AbortController, so tools are removed cleanly when the page lifecycle ends.

What is real, and what is intentionally simulated

The map uses real OpenStreetMap tiles and visible attribution.

The London locations, route estimates, and ride quotes are deterministic demo data. MapsMCP does not claim live traffic, real restaurant availability, or actual ride booking. That keeps the demo dependable and makes the WebMCP interaction the focus.

Why it matters

MapsMCP is a small prototype for a much bigger idea.

A person should not have to explain a map to an agent through clicks and screenshots. An agent should not have to guess what a map gesture did.

WebMCP gives the map a shared language. The person stays in control. The agent stops guessing.

Built With

Share this project:

Updates

Submission history