Mapy.com MCP Server (unofficial)

🇬🇧 English · 🇨🇿 Čeština

An MCP server for the Mapy.com REST API — geocoding, route planning, distance matrices, elevation, route elevation profiles, static maps, panoramas and time zones.

Unofficial project. Not a product or service of Seznam.cz a.s. Map data © Seznam.cz a.s. and others.

The design write-up and the API pitfalls it works around are in DESIGN.md.

Installation

You need an API key from developer.mapy.com. The key must have the services you intend to use enabled in the portal — otherwise the API returns 403 even with a valid key.

Claude Code

claude mcp add mapy --env MAPY_API_KEY=your_key -- uvx mapy-cz-mcp-server-unofficial

Claude Desktop

{
  "mcpServers": {
    "mapy": {
      "command": "uvx",
      "args": ["mapy-cz-mcp-server-unofficial"],
      "env": { "MAPY_API_KEY": "your_key" }
    }
  }
}

Tools

Every coordinate-taking tool accepts either a place name or coordinates: start="Prague" works the same as start={"lat": 50.087, "lon": 14.421}.

Resources

Prompts

naplanuj-vylet (plan a trip), porovnej-trasy (compare routes), kde-to-je (where is it).

Configuration

The key is sent only in the X-Mapy-Api-Key header, never in the URL — so it stays out of logs and history.

Attribution

Using data from the API requires displaying attribution. Static maps and panoramas have attribution burned into the image. For geocoding and routing your application must display it — every non-image response therefore carries an attribution field, and the full text is in the mapy://attribution resource.

Development

uv sync --extra dev
uv run pytest                          # tests run against fixtures, no credits
uv run ruff check src tests scripts
uv run ruff format src tests scripts
uv run python -m mapy_mcp              # run on stdio

Tests run against stored fixtures via respx, so they need no API key and spend no credits.

See CONTRIBUTING.md for the full contributor guide.

API drift watcher

The Mapy.com REST API specs are public, so there's no reason to wait for something to break in production:

uv run python scripts/api_drift.py            # compare against api-fingerprint.json
uv run python scripts/api_drift.py --update   # refresh the fingerprint after adapting to changes

api-fingerprint.json stores a fingerprint of the API surface — paths, parameters, their types, enumerations and limits, plus the auth scheme. It is not a copy of the specs but a derived description of the interface, so a diff shows exactly what this server cares about.

The Mapy.com REST API watcher workflow runs every Monday. When the interface changes the job fails and opens an issue with the diff (or comments on an already-open one).

Releasing

Publishing goes through PyPI Trusted Publishing, so there is no API token in the repository.

One-time setup:

1. On PyPI, register a pending publisher for mapy-cz-mcp-server-unofficial: repository xxBedy/mapy-cz-mcp-server-unofficial, workflow release.yml, environment pypi.
2. On GitHub, create the pypi environment (Settings → Environments).

Each release:

# 1. bump version in pyproject.toml
# 2. tag it — the tag must match the version, or the workflow fails
git tag v0.1.0 && git push origin v0.1.0

The release.yml workflow runs the full CI, builds the package and publishes it.

Contributing

Contributions are welcome! Read CONTRIBUTING.md (how to set up your environment, run tests and open a PR) and the CODE_OF_CONDUCT.md. Report vulnerabilities per SECURITY.md. Notable changes are tracked in CHANGELOG.md.

License

MIT — see LICENSE. The license covers this server's code, not the map data, which is subject to the Mapy.com terms.