seismic-mcp

seismic-mcp

一个统一的 Model Context Protocol 服务，用于获取全球地震数据。并行查询 20 个地震机构；匹配不同机构报告的同一场地震；呈现震级和位置差异，让 AI Agent 看到单一数据源可能掩盖的信息。

状态

已实现：

• 已接入 20 个机构。 FDSN-event：USGS、EMSC、IRIS、INGV、GeoNet、GFZ、NOA、IPGP、NCEDC、SCEDC、ISC、SED、BMKG、NIEP、RESIF、KNMI、NRCAN。自定义（非 FDSN）：JMA（日本）、AFAD（土耳其）、IMO（冰岛）。
• 跨机构数据协调。 时空聚类、主报告选择（当地主管机构 > 欧洲地区的 EMSC > USGS）、差异检测（震级／位置／深度差异）。经审查的公告优先于初步报告。
• 七个 MCP 工具： find_events、get_event、compare_sources、find_discrepancies、list_recent_by_agency、get_agency_info、list_agencies。
• TTL 缓存（60 s），并对进行中的请求去重：重复查询耗时不到 100 ms。
• 57 个单元测试，覆盖解析器、匹配、主报告选择、主管机构、数据协调和缓存。
• HTTP 前端，用于手动检查：表单 + Leaflet 地图 + 并排比较抽屉。

尚未实现：EMSC eventid 映射（交叉引用 USGS／EMSC ID，以实现更精确的匹配）、填充 known_aliases.json、按事件设置多区域主管机构（土耳其同时纳入 KOERI 和 AFAD）。

安全

提供多个地震机构的报告数据，用于研究、新闻报道、态势感知和兴趣探索。它不是预警系统。地震报告到达时，报告所在地已经发生震动。有关地震防灾准备和应急响应，请咨询当地官方机构（USGS ShakeAlert、JMA Earthquake Early Warning 等）。报告机构通常会修订初步震级和位置；切勿依据单一读数作出安全决策。

运行

作为 MCP 服务运行（Claude Desktop、VS Code 等）

发布到 PyPI 后，无需检出代码库 — uvx 会获取并运行它：

uvx seismic-mcp

添加到 claude_desktop_config.json — Windows 路径为 %APPDATA%\Claude\claude_desktop_config.json，macOS 路径为 ~/Library/Application Support/Claude/claude_desktop_config.json：

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

也可以从本地检出的代码库运行（用于开发）：

uv sync
uv run python server.py

重启 Claude Desktop。工具会显示在工具菜单的 seismic-mcp 服务下。

作为 Web 前端运行（手动检查）

uv run python web.py

然后打开 http://127.0.0.1:8765/。使用与 MCP 服务相同的代码路径，只是通过 HTTP 配合简易界面提供服务。

测试

uv run pytest

架构

server.py              FastMCP entry point — 7 @mcp.tool functions
web.py                 FastAPI HTTP wrapper around the same tools
src/
  schemas.py           Pydantic models: SourceReport, ReconciledEvent, ...
  adapters/
    base.py            SeismicAdapter protocol
    fdsn.py            Header-aware FDSN-event adapter (handles 17 networks)
    afad.py            Custom AFAD JSON adapter
    jma.py             Custom JMA list.json adapter
    imo.py             Custom IMO GeoJSON adapter
    __init__.py        Registry: make_adapter(code), supported_agencies()
  authorities.py       Regional-authority bbox lookup
  matching.py          Spatiotemporal clustering with mag-scaled thresholds
  prime_selection.py   Headline-report selection rules
  reconcile.py         Cluster → ReconciledEvent with spreads
  cache.py             TTL cache + in-flight de-dup
  tools/               One file per MCP tool
data/
  agency_metadata.json    Per-agency coverage, latency, notes
  region_authorities.json Region bboxes → authoritative agency
  known_aliases.json      (manual fallback for matching, currently {})
tests/                 pytest suite — 57 tests, fast (<1s)
static/index.html      Single-page UI for the HTTP frontend