.codex-plugin— mcp server

<div align="center"> <h1>@cyanheads/openstreetmap-mcp-server</h1> <p><b>Geocode, reverse geocode, and run Overpass spatial queries on OpenStreetMap data via MCP. STDIO or Streamable HTTP.</b> <div>6 Tools</div> </p> </div>

<div align="center">

</div>

<div align="center">

</div>

<div align="center">

Public Hosted Server: https://openstreetmap.caseyjhand.com/mcp

</div>

Tools

6 tools for geocoding and spatial queries against OpenStreetMap data:

openstreetmap_geocode

Convert a place name or address to geographic coordinates via Nominatim/OpenStreetMap.

• Two input modes: free-form query string (e.g., "Space Needle Seattle") or structured address fields (street, city, state, country, postal code) — mutually exclusive
• Country filtering via ISO 3166-1 alpha-2 codes (countrycodes)
• Data layer filtering: address, poi, railway, natural, manmade
• Feature type restriction: country, state, city, settlement
• Optional extra OSM tags (phone, website, opening_hours, wikidata)
• Preferred language override via BCP 47 code
• Returns results ordered by Nominatim importance score (global prominence)
• Results include coordinates, structured address, bounding box, OSM type/ID for chaining into openstreetmap_lookup

openstreetmap_reverse

Convert latitude/longitude to the nearest address or named place.

• Zoom-level control for address detail: 18=building, 16=street, 14=neighbourhood, 12=town, 10=city, 8=county, 5=state, 3=country
• Layer filtering for matched OSM object type
• Optional extra OSM tags and language preference
• Returns structured address breakdown, OSM type/ID, and bounding box

openstreetmap_lookup

Fetch full Nominatim address records for known OSM object IDs.

• Accepts single ID or array of up to 50 IDs
• IDs must be prefixed with N (node), W (way), or R (relation): e.g., "N240109189", "W50637691", "R146656"
• Efficient alternative to a full geocoding round-trip when OSM IDs are already known (e.g., from an Overpass result)
• Reports not_found list for IDs that returned no result
• Optional extra OSM tags and language preference

openstreetmap_query_nearby

Find OSM features within a radius around a point via the Overpass API.

• Primary tool for "what's near X?" spatial queries
• Supports amenity shortcut for common POI types (hospital, pharmacy, restaurant, cafe, school, atm) or tag_key + tag_value for any OSM category (leisure=park, shop=supermarket, natural=peak)
• Configurable radius up to 50km; keep under 5km for dense urban POI queries
• Element type filtering: node (standalone POIs), way (buildings/areas), relation (complex structures)
• Limit up to 500 results; truncated flag signals when more exist
• Returns OSM type/ID, coordinates, name, and full tag set for each feature

openstreetmap_query_bbox

Find OSM features within a rectangular geographic bounding box.

• Useful for area surveys where proximity to a single point isn't the goal
• Same amenity / tag_key + tag_value interface as openstreetmap_query_nearby
• Configurable timeout for large bounding boxes or dense areas
• Limit up to 500 results with truncated flag

openstreetmap_query_raw

Execute arbitrary Overpass QL for queries the convenience tools don't cover.

• Full Overpass QL expressiveness: multi-type queries, union queries, relation membership, historical queries
• Query must include [out:json]; server injects [timeout:N] if absent
• Returns raw element array — structure varies by query type (nodes have lat/lon, ways have nodes[], relations have members[])
• Validate complex queries at overpass-turbo.eu before use

Features

Built on @cyanheads/mcp-ts-core:

• Declarative tool definitions — single file per tool, framework handles registration and validation
• Unified error handling across all tools
• Pluggable auth (none, jwt, oauth)
• Swappable storage backends: in-memory, filesystem, Supabase, Cloudflare KV/R2/D1
• Structured logging with optional OpenTelemetry tracing
• Runs locally (stdio/HTTP) or on Cloudflare Workers from the same codebase

Nominatim/Overpass-specific:

• Nominatim usage policy compliance: configurable User-Agent via OSM_USER_AGENT, rate-limit-aware request handling
• OSM attribution on every response (Data © OpenStreetMap contributors, ODbL 1.0)
• Private instance support — override OSM_NOMINATIM_BASE_URL and OSM_OVERPASS_BASE_URL for self-hosted or mirror endpoints
• Structured error contracts: no_results, no_coverage, invalid_id_format, invalid_tag, query_timeout, rate_limited, query_error, result_too_large — all with actionable recovery hints

Agent-friendly output:

• Attribution on every response — agents can surface the ODbL license notice as required
• Structured output contracts — coordinates, OSM IDs, address fields, and tag maps in consistent shapes
• Cross-tool chaining: Overpass results carry osm_type + osm_id that feed directly into openstreetmap_lookup for full address records

Getting started

Self-Hosted / Local

Add the following to your MCP client configuration file.

{
  "mcpServers": {
    "openstreetmap-mcp-server": {
      "type": "stdio",
      "command": "bunx",
      "args": ["@cyanheads/openstreetmap-mcp-server@latest"],
      "env": {
        "MCP_TRANSPORT_TYPE": "stdio",
        "MCP_LOG_LEVEL": "info"
      }
    }
  }
}

Or with npx (no Bun required):

{
  "mcpServers": {
    "openstreetmap-mcp-server": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "@cyanheads/openstreetmap-mcp-server@latest"],
      "env": {
        "MCP_TRANSPORT_TYPE": "stdio",
        "MCP_LOG_LEVEL": "info"
      }
    }
  }
}

For Streamable HTTP, set the transport and start the server:

MCP_TRANSPORT_TYPE=http MCP_HTTP_PORT=3010 bun run start:http
# Server listens at http://localhost:3010/mcp

Prerequisites

• Bun v1.3.0 or higher (or Node.js ≥24.0.0).
• No API key required — Nominatim and Overpass are public APIs. For heavy use, consider pointing OSM_NOMINATIM_BASE_URL and OSM_OVERPASS_BASE_URL at self-hosted or mirror instances.

Installation

1. Clone the repository:

git clone https://github.com/cyanheads/openstreetmap-mcp-server.git

1. Navigate into the directory:

cd openstreetmap-mcp-server

1. Install dependencies:

bun install

Configuration

All configuration is validated at startup via Zod schemas in src/config/server-config.ts. Key environment variables:

Running the server

Local development

• Build and run the production version:

  # One-time build
  bun run rebuild

  # Run the built server
  bun run start:http
  # or
  bun run start:stdio

• Run checks and tests:

  bun run devcheck  # Lints, formats, type-checks, and more
  bun run test      # Runs the test suite

Project structure

Development guide

See CLAUDE.md for development guidelines and architectural rules. The short version:

• Handlers throw, framework catches — no try/catch in tool logic
• Use ctx.log for logging, ctx.state for storage
• Register new tools and resources in the createApp() arrays

Contributing

Issues and pull requests are welcome. Run checks and tests before submitting:

bun run devcheck
bun run test

License

This project is licensed under the Apache 2.0 License. See the LICENSE file for details.

Map data from OpenStreetMap contributors, available under the Open Database License (ODbL).