OpenStreetMap Tagging Schema MCP Server

<!- - CI/CD Status - ->

<!- - Package Information - ->

<!- - Dependencies - ->

<!- - Code Quality & Security - ->


[](docs/deployment/security.md# slsa-build-provenance)

<!- - Project Information - ->

# 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.

Current Status: Production-ready MCP server, actively maintained and continuously improved. The service is deployed and accessible at https://mcp.gander.tools/osm-tagging/.

We welcome your feedback! Have ideas for improvements? Found a bug? Want to discuss features? Please open an issue or start a discussion.

# 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.
• Not a public API for general use: The deployed service at mcp.gander.tools is intended for integration with AI agents, not for direct HTTP requests or high-volume automated queries. Please do not attempt to abuse the service with DDoS attacks or excessive traffic.

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

# Features

7 MCP Tools organized into 3 categories:

• Tag Query (2 tools): Query tag values and search tags
• Preset Discovery (2 tools): Search and explore OSM presets with detailed configurations
• Validation (3 tools): Validate tags, check for deprecated tags, suggest improvements

📖 Full tool reference: docs/api/

# Installation

# # Using npx (Recommended)

#  No installation needed - run directly
npx @gander-tools/osm-tagging-schema-mcp

# # Using Docker

#  Run with stdio transport
docker run -i ghcr.io/gander-tools/osm-tagging-schema-mcp:latest

📖 More options: docs/user/installation.md (source installation, verification, troubleshooting)

# Quick Start

# # With Claude Code CLI

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

#  Use in conversations
#  Ask Claude: "What OSM tags are available for restaurants?"
#  Ask Claude: "Validate these tags: amenity=parking, capacity=50"

# # With Claude Desktop

Add to your Claude Desktop configuration:

{
  "mcpServers": {
    "osm-tagging-schema": {
      "command": "npx",
      "args": ["@gander-tools/osm-tagging-schema-mcp"]
    }
  }
}

📖 Next steps:

• Configuration Guide - Setup for Claude Code/Desktop and custom clients
• Usage Guide - Tool examples and workflows
• API Reference - Complete tool documentation
• Deployment Guide - Production HTTP/Docker deployment

# # Testing with MCP Inspector

Test and debug the server using the official MCP Inspector:

#  Test published package (quickest)
npx @modelcontextprotocol/inspector npx @gander-tools/osm-tagging-schema-mcp

#  Test Docker image
npx @modelcontextprotocol/inspector docker run - -rm -i ghcr.io/gander-tools/osm-tagging-schema-mcp

The Inspector provides an interactive web UI to test all tools, inspect responses, and debug issues.

📖 Complete inspection guide: docs/development/inspection.md (includes HTTP transport testing)

# Development

Built with Test-Driven Development (TDD) and Property-Based Fuzzing:

• Comprehensive test suite (unit + integration) with 100% pass rate
• Property-based fuzz tests with fast-check for edge case discovery
• Continuous fuzzing in CI/CD (weekly schedule + on every push/PR)

npm install      #  Install dependencies
npm test         #  Run all tests
npm run test:fuzz #  Run fuzz tests
npm run build    #  Build for production

📖 Development guides: docs/development/development.md | docs/development/fuzzing.md

# Contributing

Contributions welcome! This project follows Test-Driven Development (TDD).

1. Fork and clone the repository
2. Install dependencies: npm install
3. Create a feature branch
4. Write tests first, then implement
5. Ensure all tests pass: npm test
6. Submit a pull request

📖 Guidelines: docs/development/contributing.md

# Documentation

# # Quick Navigation

Choose your path:

| I want to... | Go to |
|- -- -- -- -- -- --|- -- -- --|
| Install and run the server | Installation Guide |
| Configure with Claude Code/Desktop | Configuration Guide |
| Learn how to use the tools | Usage Guide → API Reference |
| Test and debug the server | Inspection Guide |
| Deploy in production (HTTP/Docker) | Deployment Guide |
| Fix issues or errors | Troubleshooting Guide |
| Contribute to the project | Contributing Guide |

# # Complete Documentation

User Guides:

• Installation - Setup guide (npx, Docker, source)
• Configuration - Claude Code/Desktop configuration
• Usage - Tool examples and workflows
• API Reference - Complete tool documentation
• Troubleshooting - Common issues and solutions

Developer Docs:

• Contributing - Contribution guidelines (TDD workflow)
• Development - Development setup and debugging
• Inspection - MCP Inspector testing guide
• Fuzzing - Security fuzzing and property testing
• Roadmap - Project roadmap and future features
• Release Process - Release and publishing workflow

Deployment Docs:

• Deployment - HTTP/Docker production deployment
• Security - Security features, provenance, and SLSA

Project Info:

• CHANGELOG.md - Version history

# License

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