Osm Tagging Schema Mcp

OpenStreetMap Tagging Schema MCP Server

What is this?

This is a Model Context Protocol (MCP) server designed specifically for AI agents and LLM applications. It acts as a bridge between artificial intelligence systems and the comprehensive OpenStreetMap tagging knowledge base provided by the official @openstreetmap/id-tagging-schema library.

Project status

This project is a Proof of Concept. It gives real value in some areas and has known gaps in others, both described honestly below.

• It works with the latest tagging schema, @openstreetmap/id-tagging-schema v7.
• A better replacement tool is being worked on. It will arrive later than originally planned, and no date is promised.

Bug reports and ideas: open an issue or start a discussion.

How it works

The server runs over stdio (default) or HTTP and exposes the tagging schema as MCP tools. Every tool reads the schema data shipped in @openstreetmap/id-tagging-schema (presets, fields, deprecated tags, translations) and answers from it deterministically. There is no network access to OSM and no AI inside the server: the AI agent calls the tools and interprets the results.

Validation checks a tag against the schema: known key, value allowed by the matching field, deprecated key/value with a suggested replacement.

What works and what doesn't

The tool has limitations. Know what to expect before relying on it: it answers from the schema data only, and a part of the tags that exist in the wild or on the OSM wiki is not covered.

Tool	Works	Limitations
validate_tag	Popular tags accepted (100%), almost no false deprecated alarms (99.2%)	Detects only ~20% of wiki-deprecated tags; typos and foreign values are accepted as valid (custom tags are allowed); railway=platform and railway=station are wrongly flagged as deprecated
validate_tag_collection	Consistent with validate_tag (100%)	Same gaps as validate_tag; control characters are not reported
suggest_improvements	Preset matched for 92% of popular tags	Typos and foreign values usually yield suggestions, not a problem report
get_tag_values	97% of taginfo values present; bad keys and limits rejected	A few taginfo values are missing from the lists
search_tags	Finds 60% of keys by name	No typo tolerance despite the fuzzy-matching description; keys with a colon (addr:street) are often missed; limit of 0 or negative not always rejected; access returns a keyMatches item without key
search_presets	Preset found for 69% of popular tags (56% in top 3)	Multi-word queries (bicycle parking) can return nothing; weak ranking; limit of 0 or negative not always rejected
get_preset_details	Preset exists for 93% of popular tags; unknown ids always rejected	Some popular tags (e.g. historic=*, craft=grinding_mill, railway=stop) have no preset
compare_tags	Matches local computation (100%); text and JSON input give identical output	Compares any tag sets, so it never says a tag is wrong; only malformed input is rejected
flat_to_json	Lossless, including ;, spaces, =, Unicode, : and /	Duplicate keys and control characters are accepted silently
json_to_flat	Lossless round-trip (100%); bad input rejected	Keys are not sorted alphabetically, input order is kept

Across all tools, invalid input never crashed the server: errors are readable or the result is an empty list.

Summary

Useful where deterministic logic is enough: format conversion, comparing tag sets, reading presets and values, validating popular tags. Weakest areas: deprecated tag detection and search (typos, multiple words, colon keys).

What this is NOT

⚠️ Important clarifications:

• Not a standalone application: This server requires integration with AI systems (like Claude Code or Claude Desktop) to be useful. It has no user interface or web frontend.
• Not for direct human use: Without an AI agent as an intermediary, this tool provides no value to end users. It's designed exclusively for programmatic access by LLM applications.

If you're looking for a user-facing OSM tagging tool, consider iD editor or JOSM instead.

Installation

Add the server to Claude Code (stdio):

# npx
claude mcp add --transport stdio osm-tagging-schema -- npx -y @gander-tools/osm-tagging-schema-mcp

# Docker
claude mcp add --transport stdio osm-tagging-schema -- docker run -i --rm ghcr.io/gander-tools/osm-tagging-schema-mcp:latest

HTTP transport

stdio is the default. Set TRANSPORT=http to serve over HTTP (streamable, port 3000 in the Docker image):

Variable	Default	Meaning
TRANSPORT	stdio	stdio or http
PORT	3000	HTTP port
HOST	0.0.0.0	HTTP bind address
CORS_ORIGINS	http://localhost:6274,https://mcp.ziziyi.com	Comma-separated allowed CORS origins
LOG_LEVEL	INFO	SILENT, ERROR, WARN, INFO, DEBUG

docker run --rm -p 3000:3000 -e TRANSPORT=http ghcr.io/gander-tools/osm-tagging-schema-mcp:latest

Endpoints: GET /health (liveness), GET /ready (schema loaded), GET /version.

License

GNU General Public License v3.0 - See LICENSE file for details.