Documentation / OpenStreetMap MCP server

OpenStreetMap MCP server

Use MCP for local address and business search, regional POI discovery, OpenStreetMap queries, basemaps, navigation and elevation.

On this page

Find destinations and businesses with MCP

Connect to https://api.mapsource.io/mcp using Streamable HTTP and a Bearer API key in the transport headers. Retrieve current schemas through tools/list or /mcp.json.

Use geo_search with operation lookup for addresses, businesses, brands, landmarks and populated places. Pass the current map/GPS focus in lat/lon as a soft bias; only bounded=true restricts a supplied bbox. Use discover to enumerate mapped businesses in a viewport, polygon or travel-time region.

Use find_features for category-based OSM feature geometry and overpass_query for arbitrary QL. The /docs/agents guide includes the MCP client connection code used by these examples.

// Address/business suggestions near the current map focus.
const lookup = await client.callTool({
  name: "geo_search",
  arguments: { operation: "lookup", q: "Starbucks", lat: 45.52, lon: -122.68, limit: 8 }
});

// Cafés reachable on foot, ordered by measured travel time.
const discovery = await client.callTool({
  name: "geo_search",
  arguments: {
    operation: "discover", category: "coffee",
    lat: 45.52, lon: -122.68, minutes: 15,
    costing: "pedestrian", rankBy: "travel_time", limit: 8
  }
});

// OSM geometry for an overlay; this tool uses named bbox coordinates.
const features = await client.callTool({
  name: "find_features",
  arguments: { category: "cafes", south: 45.51, west: -122.69,
    north: 45.53, east: -122.67, limit: 100 }
});

for (const result of [lookup, discovery, features]) {
  if (result.isError) throw new Error(JSON.stringify(result.content));
  console.log(result.structuredContent ?? result.content);
}

Feature-search parameters

find_features requires a named category and explicit south, west, north, and east bounds. Latitude is constrained to ±85 degrees and longitude to ±180. Each axis can span at most 0.5 degrees, and the box must be ordered. The optional limit defaults to 100 and accepts 1–500 objects.

Category	OSM selector
`cafes`	`amenity=cafe`
`restaurants`	`amenity=restaurant`
`buildings`	`building=*`
`parks`	`leisure=park`
`schools`	`amenity=school`
`hospitals`	`amenity=hospital`
`transit_stops`	`public_transport=platform`
`drinking_water`	`amenity=drinking_water`
`trails`	`highway=path`

These helpers match specific OSM tags; they are not exhaustive semantic categories. For example, trails matches highway=path, not every track or footway. Use overpass_query for a different definition or a union of tags.

A bounded agent workflow

Read service_status and verify the dataset.
Choose a small explicit bounding box; obtain it from the user, map viewport, or an appropriate geocoder.
Call find_features with the category and a small output limit.
Check isError, engine mode, and returned objects before summarizing results.
Use basemap_catalog to configure a map, and elevation for selected coordinates if the user needs terrain height.

Geocode addresses before calling find_features. The tool accepts a bounding box and category. Its output limit caps returned objects and does not provide a total count.

The agent setup guide includes client configuration, available tools, authentication, result formats, and payment handling.

Access and limits

Address/business lookup and regional discovery are included in every subscription plan; x402 Overpass payments do not grant search access. Lookup returns at most 20 ranked suggestions. Discovery regions span at most one degree per axis; generated isochrones accept 1–30 minutes, and travel-time ranking compares at most the 25 nearest candidates. For pagination, coverage and request accounting, see /docs/places-api and /docs/limits#search-accounting.

find_features accepts a bounding box up to 0.5 degrees per axis and a limit of 1–500 objects. Service status and basemap discovery are public. Authenticated query results above the inline limit can be returned as result handles.

See plan limits for request allowances and error handling for quota and retry behavior.

Responses and examples

Check isError before processing tool results. geo_search returns the REST response in structuredContent.data. Lookup uses mapsource-lookup.v1; discovery uses mapsource-discovery.v1. Preserve string OSM IDs and source-provided address fields. When ambiguous is true or bestMatchId is null, ask the user to choose. Follow pagination.nextOffset and narrow discovery regions when coverage.truncated is true. Lookup index timestamps are independent of the Overpass dataset. Use geo_data with operation status for subsystem availability and freshness.

Example responses and timing measurements · Current service status

Attribution

Find Mapsource in the official MCP Registry as io.github.robit-man/mapsource. Include OpenStreetMap attribution when displaying or distributing returned map data.

Source and reference · Mapsource attribution guide

Questions about this guide? Contact support.