Metadata-Version: 2.5
Name: iran-quake-mcp
Version: 0.1.0
Summary: Unofficial read-only MCP server for earthquakes in Iran: latest, search, strongest, detail and statistics from USGS, EMSC and IRSC.
Project-URL: Homepage, https://github.com/sepehr071/iran-quake-mcp
Project-URL: Issues, https://github.com/sepehr071/iran-quake-mcp/issues
Author-email: Sepehr Radmard <sepehrr80@gmail.com>
License-Expression: MIT
License-File: LICENSE
Keywords: earthquake,emsc,iran,mcp,model-context-protocol,seismology,usgs
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
Requires-Python: >=3.10
Requires-Dist: curl-cffi>=0.16.3
Requires-Dist: httpx-curl-cffi>=0.1.5
Requires-Dist: httpx>=0.27
Requires-Dist: mcp<3,>=2.2
Description-Content-Type: text/markdown

<!-- mcp-name: io.github.sepehr071/iran-quake-mcp -->

# iran-quake-mcp: Iran earthquakes MCP server for AI agents

Unofficial, read-only MCP server for earthquakes in Iran (زلزله ایران): latest quakes, history search, the strongest
events, one event in full, and activity statistics, from the public USGS, EMSC and IRSC feeds. Works in Claude, Cursor and Copilot.

## For AI agents

- **What:** earthquake data for Iran from USGS ComCat (`source="usgs"`, default), EMSC via SeismicPortal (`source="emsc"`) and the Iranian Seismological Center (`source="irsc"`, only its latest ~20 events, with province names). Sources are not merged; ids differ.
- **Install:** `uvx iran-quake-mcp` or `claude mcp add iran-quake -- uvx iran-quake-mcp`. Transport: stdio. Needs [uv](https://docs.astral.sh/uv/getting-started/installation/) (Python 3.10+).
- **Auth:** none. Optional `IRAN_QUAKE_MCP_PROXY` (HTTP proxy URL, comma list allowed); system proxy settings are ignored.
- **Access:** read-only, no confirmation needed.
- **Units:** `time_utc` (UTC) and `time_tehran` (UTC+03:30, no daylight saving); search dates are UTC; `depth_km` in kilometres; `mag_type` (mb, ml, mw...) says which magnitude it is.
- **Replies:** at most 50 events per call (`limit` 1-50), about 11 KB at the maximum.
- **Places:** USGS and EMSC have no province field (USGS gives the nearest town, EMSC a region). `place` accepts a province name (Tehran, Kerman, Hormozgan, Khuzestan, Fars, Sistan and Baluchestan, Kermanshah, Razavi Khorasan, East Azerbaijan, West Azerbaijan, Bushehr, Mazandaran), which selects an approximate box that overlaps its neighbours; other text is matched against the place text. IRSC places are `Town, Province`.
- **IRSC:** read from `http://irsc.ut.ac.ir/events_list.xml` (plain HTTP, its https is closed). It holds only the latest ~20 events, so `more` is true when the dates reach further back; the data is licensed for non-commercial, humanitarian use and must cite the Iranian Seismological Center (University of Tehran). Not a warning service.

## Tools

| Tool | What it does |
|---|---|
| `eq_latest` | Most recent earthquakes (min magnitude, hours back, source), newest first |
| `eq_search` | Search by UTC date range, magnitude range, bounding box and place text |
| `eq_significant` | Strongest earthquakes of the last N days, largest first |
| `eq_detail` | One event in full by id (USGS: review status, felt/shaking, tsunami flag, quality; EMSC: agency, update time; IRSC: nearest towns) |
| `eq_stats` | Counts for a window: by magnitude band, top places, strongest event |

By default only events inside a coarse Iran outline (about 0.3 degrees on land borders; includes the Iranian Persian Gulf, Gulf of Oman and south Caspian) whose place text names Iran, Persian Gulf, Gulf of Oman or Caspian Sea are returned, so border-region rows across the border are dropped (`iran_only=false` returns everything in the bounding box 24-40 N, 43.5-64 E).

## Development

```bash
uv sync
uv run ruff check . && uv run ruff format --check .
uv run python -m pytest -q          # offline
uv run python -m pytest -m live -q  # real USGS/EMSC
uv build
```

Data: USGS Earthquake Hazards Program and EMSC; see their terms of use. MIT licensed.
