izmirmcp

A read-only Model Context Protocol server that gives AI agents trustworthy access to İzmir's open city data.

Language: English · Türkçe

Contents

• Why izmirmcp · Quick start · Tools · Prompts and resources
• Examples · Architecture · Configuration
• Data sources · Security · Contributing · License

English

This README is the primary English document; a full Turkish version is in README.tr.md.

Why izmirmcp

• 36 tools across transit, city services, water, environment and the open-data catalog.
• One envelope for every answer: ok, summary, data, freshness, sources, limits, warnings, next_queries, error, result_info (contract).
• Honest failures: an unavailable upstream is a typed error (source_unavailable, source_timeout, source_rate_limited), never silently empty data.
• Hardened HTTP surface: body caps, rate limits, API keys, Origin allowlist, structured logs.
• Stable contract: tool names and schemas only change additively (policy).

Quick start

uvx (PyPI, from v0.1.0):

uvx izmir-mcp stdio

Docker / GHCR:

docker run --rm -i ghcr.io/zexy2/izmir-mcp python -m app.stdio      # stdio
docker run -p 8000:8000 -v izmir-data:/data ghcr.io/zexy2/izmir-mcp  # HTTP on /mcp/

From source:

python3.11 -m venv .venv && .venv/bin/pip install -e ".[dev]"
.venv/bin/python -m app.stdio   # or: python -m app.main (Streamable HTTP, http://127.0.0.1:8000/mcp/)

Generic stdio config (most clients use this mcpServers shape):

{
  "mcpServers": {
    "izmir": { "command": "uvx", "args": ["izmir-mcp", "stdio"] }
  }
}

More options: install guide, client setup guides (TR).

Tools

Full input/output contracts: tool reference.

Transit

City services

Water

Environment

Data & server

Prompts and resources

• Workflow prompts: gunun_ozeti, veri_kesfi, toplu_ulasim, otobus, pazar_ve_duyurular, sehir_hizmetleri, nobetci_eczane, rota_karsilastir, bugun_ne_yapsam, su_durumu_raporu, eczane_ve_ulasim, sehir_simdi.
• Resources: izmir://coverage, izmir://sources, izmir://schema/catalog, izmir://reference/fares, izmir://reference/lines.

See MCP interface.

Example conversations

1. "Konak to Karşıyaka: ferry, metro + İZBAN or bus — which is faster and cheaper?"
2. "Is there a market in Bornova today, and how are air quality and transport notices?"
3. "Any water outage in Buca, and how full are the dams?" (the İZSU outage API sometimes returns 500; the agent sees a typed error)
4. "On-duty pharmacy in Karşıyaka and buses arriving at the nearest stop?"
5. "What is the state of İzmir right now for transport, air and water?"

Architecture

flowchart LR
  C[MCP client] -->|stdio / Streamable HTTP| S[izmirmcp server]
  S --> G[HTTP guards: auth, rate limit, Origin]
  S --> T[36 tools + resources + prompts]
  T --> V[services: envelope, freshness, typed errors]
  V --> K[connectors + cache]
  V --> L[(local SQLite: GTFS, DataStore copies)]
  K --> U[İzmir open data: CKAN, openapi.izmir.bel.tr, ESHOT, İZSU, İZDENİZ]

Configuration

All settings are IZMIR_MCP_* environment variables. Before exposing HTTP publicly, set IZMIR_MCP_API_KEYS, IZMIR_MCP_REQUIRE_AUTH=true and IZMIR_MCP_ALLOWED_HOSTS. See configuration and deployment. Health endpoints: /healthz, /readyz (never checks upstream), /status (monitoring).

Data sources and disclaimer

Data comes from İzmir Büyükşehir Belediyesi open data (CKAN and openapi.izmir.bel.tr), ESHOT, İZSU, İZBAN, İZDENİZ and İzmir Metro; reference points are © OpenStreetMap contributors (ODbL 1.0). Status per source: sources, reachability. Known gaps (no live traffic index, no İZBAN notice feed, GTFS calendar expiry): limits.

This is an unofficial project. Data may be stale or incomplete; verify critical information (e.g. pharmacies by phone) with the publishing institution. Public access does not imply a data licence.

Security

Report vulnerabilities privately: SECURITY.md. Threat model: docs/security.md; scan results: docs/development/reports/security-report.md.

Contributing

See CONTRIBUTING.md and the Code of Conduct. Tests run offline: .venv/bin/python -m pytest -q (development).

Documentation

Response contract · Tool reference · MCP interface · Deployment · Configuration · Data sources · Source reachability · Monitoring · Privacy · Security / threat model · Security report · API access · Browser and CORS · Local SQL · Place resolution · GTFS schedule · Registry · Tool migration policy · Development · Limits · Install (EN) · Install (TR) · Launch drafts

License and acknowledgements

Code is released under the MIT License. Endpoint lists adapted from Apache-2.0 projects (halilcengel/IzmirMCP, AtaCanYmc/izmir-open-data-py) are attributed in NOTICE. The architecture and response contract are inspired by istanbulmcp. City data licences belong to the publishing institutions.