earthquake-mcp-server

---

概览

来自 USGS ComCat 和 EMSC SeismicPortal 的地震数据。获取实时地震数据流，按时间、震级、深度和位置搜索及统计地震事件，并获取单个事件的完整分析详情。

工具

工具	描述
earthquake_get_feed	按震级等级和时间范围获取 USGS 预计算的实时地震数据流
earthquake_search_events	按时间范围、震级、深度、位置半径、PAGER 警报等级或有感报告搜索地震
earthquake_count_events	统计符合筛选条件的地震数量，无需获取完整记录
earthquake_get_event	按 USGS 事件 ID 获取特定地震的完整详情

资源

资源	描述
earthquake://feed/{magnitude_tier}/{time_window}	USGS 实时数据流的第一页（有界），并提供精确的续传 URI
earthquake://feed/{magnitude_tier}/{time_window}/page/{cursor}	使用返回的 next_uri 继续获取保留的数据流版本
earthquake://event/{event_id}	按 ID 获取完整的 USGS 地震事件详情，作为可注入的上下文，其中包括与 earthquake_get_event 相同的 detail 产品投影

功能参考

earthquake_get_feed _工具

• 选择震级等级（all、1.0、2.5、4.5、significant）和时间窗口（hour、day、week、month）。USGS 会缓存这些数据源；如需查询历史数据或使用筛选条件，请使用 earthquake_search_events。
• 返回事件、页数、生成时间和数据源 URL。all 包含微震；significant 是 USGS 根据震级、震感报告和 PAGER 影响评定的结果。
• limit 默认为 100，最高可设为 1000。每页限制为 24,000 字节的序列化结果，因此可能包含较少的事件。totalCount 报告整个数据源的总数；使用相同的震级等级和时间窗口，并将 nextCursor 原样传回。
• 后续请求会读取首次读取时的数据版本，不受上游编辑影响。数据最多保留 15 分钟，但可能因容量限制而被逐出或因重启而丢失。cursor_expired 表示应在不使用游标的情况下重新开始；旧版游标也必须重新开始。

---

earthquake_search_events _工具

• 按时间、震级、深度、半径或边界框搜索 usgs 或 emsc。使用半径时，必须同时提供 latitude、longitude 和 radius_km；边界框的各条边可单独指定，支持最高 ±360° 的跨日界线边界，并会与提供的圆形范围取交集。
• 返回包含 event_type 和 EMSC 的 event_certainty 的规范化事件。ignoredFilters 列出不支持的筛选条件；queryEcho 报告实际生效的查询。
• 搜索和计数都接受任一数据源上的开放式 magnitude_type 值。product_type（所需产品，例如 moment-tensor）和 review_status（automatic 或 reviewed）仅适用于 USGS；EMSC 会在 ignoredFilters 中列出它们。空值视为未提供。
• 仅含日期的边界（包括扩展的年／年月格式）在两个数据源上都表示指定日期开始时的午夜：2026-10-10 会转换为 2026-10-10T00:00:00。显式时间和时区后缀会保留；未补零的日期部分会补零。对于 30 天默认窗口，不带时区偏移的时间按 UTC 处理。queryEcho 会显示精确生效的边界。
• 可按时间或震级升序或降序排序。limit 默认为 100，最高可设为 20,000；每次调用最多获取 100 个候选项，并返回一个 24,000 字节的序列化页面。分页使用原样返回的 nextOffset，从 1 开始计数，并保持筛选条件和排序顺序不变。queryEcho.limit 报告实际生效的上游候选项上限。搜索页面读取当前目录，因此上游编辑可能会影响后续页面。
• 震级、深度或显式时间边界严格倒置时，会在本地报错为 invalid_range，并指出两个值和恢复方法。相等边界和单一边界仍然有效；时间比较使用 UTC 时刻，包括显式偏移量。日历上无效的值会保留并交由上游拒绝。
• 非空的短上游页面会在字节整形前确定 totalCount；空的第一页会将总数确定为零，而后续页面为空时总数仍未知。上游页面满载时会查询总数；查询失败时会返回 countUnavailable。数据源和搜索请求共享 50 秒的重试总时限；搜索还包括可选的总数查询。取消操作仍会保持为取消状态。

---

earthquake_count_events _工具

• 使用与 earthquake_search_events 相同的筛选条件统计匹配项，而不获取事件。省略 start_time 时，统计最近 30 天；queryEcho 报告解析后的时间窗口和已应用的筛选条件。
• exceeds_limit 标记单次请求达到 20,000 个事件的阈值，并非检索上限：搜索可通过偏移分页检索更大的匹配集合。USGS 的 max_allowed 为 20,000，EMSC 的值为 null；ignoredFilters 列出数据源无法应用的筛选条件。

---

earthquake_get_event _工具

• 传入来自订阅源或 USGS 搜索结果 id 字段的 USGS event_id（例如 us6000sznj）。此工具目前仅接受 USGS ID。
• 返回规范化事件及可选的 detail：PAGER、ShakeMap、DYFI、矩张量、地面破坏警报、震源质量和有限断层尺寸。如果某组的投影字段均不可用，则会省略该组；信息缺失不代表影响为零。
• 空白 ID 会在本地报错；规范 ID 和别名匹配时不区分大小写。ShakeMap 会在发布时包含提供方的 code_version。

---

earthquake://feed/{magnitude_tier}/{time_window} _资源

• 选择与 earthquake_get_feed 相同的震级分级和时间窗口；所有 20 种组合均列为可浏览资源。
• 返回有界的 application/json 页面，包含现有的精简事件投影，以及 totalCount、truncated、nextCursor 和 next_uri。只要 next_uri 存在，就按原样读取。续页 URI 为 earthquake://feed/{magnitude_tier}/{time_window}/page/{cursor}。
• 订阅源资源与 earthquake_get_feed 共用保留的生成版本。缓存提示为私有且有效期为零，因为续页令牌属于发起请求的租户。被归类为 ServiceUnavailable 的上游故障会返回 feed_unavailable；被归类为 Timeout 的上游故障会返回 feed_timeout；两者均提供恢复指导，且不包含捕获的上游响应正文。可用性故障会保留数字 HTTP 状态码；HTTP 501 仍不可重试，并会指向 EMSC 搜索。其他错误类别原样传递。

---

earthquake://event/{event_id} _资源

• 传入来自订阅源或搜索结果的 USGS event_id。返回与 earthquake_get_event 相同的事件和可选 detail 产品。
• 使用该工具的 event_deleted、not_found、source_unavailable 和 source_timeout 错误约定。

功能

基于 @cyanheads/mcp-ts-core：支持 stdio 和 Streamable HTTP 传输、可插拔的身份验证（none / jwt / oauth）、可切换的存储方式（in-memory、filesystem、Supabase、Cloudflare KV/R2/D1），以及支持可选 OpenTelemetry 跟踪的结构化日志记录。

USGS/EMSC 专属功能：

• 为 USGS FDSN/GeoJSON API 和 EMSC FDSN-WS API 提供类型安全的客户端，并将二者的数据规范化为统一的地震领域架构
• 每次上游调用都会自动重试并采用退避机制，且设有单次请求超时；可检测 USGS 的限流/CDN 故障模式（返回 HTML 而非 GeoJSON），并将其映射为类型化的服务不可用错误，而不是将其解析为数据
• EMSC 的两字符 evtype 代码会依据已发布的事件类型/确定性术语表进行解码，映射到 USGS 发布的同一套词汇，因此 event_type 在两个来源中的含义一致
• 当 source=emsc 时，USGS 专属筛选条件（alert_level、min_felt、min_significance、event_type、product_type、review_status）会列入 ignoredFilters。在 USGS 上，event_type="earthquake" 会排除采石场爆破和其他非构造性记录。
• 无需 API 密钥或速率限制等级——USGS 和 EMSC 都是完全公开、无需密钥的 API

便于 Agent 使用的输出：

• 来源信息——每个响应都包含 source: "usgs" | "emsc"，以及用于标明目录和权威机构的 source_catalog/auth 字段，方便 Agent 权衡两个独立来源的结果
• 判别式输出契约——event_type 和 EMSC 的 event_certainty 会保留已发布的分类，缺失字段仍保持未知；exceeds_limit、countUnavailable 和 truncated 标志让调用方可以根据数据分支处理，而不必解析说明文字
• 响应整形——来源未发布的字段会返回 null，绝不会伪造为零（EMSC 事件中的 tsunami、status 和 mmi 始终为 null）；对 EMSC 查询移除的 USGS 专属筛选条件会列入 ignoredFilters，而不是被静默忽略
• 优雅降级——上游拒绝请求时，错误消息会显示服务自身的解释（出错参数、接受的格式），而非仅显示状态代码；后续计数请求失败时会降级为 countUnavailable，而不会导致整个搜索失败

开始使用

公共托管实例

可通过 https://earthquake.caseyjhand.com/mcp 使用公共实例——无需安装。使用 Streamable HTTP 将任意 MCP 客户端指向该实例：

{
  "mcpServers": {
    "earthquake-mcp-server": {
      "type": "streamable-http",
      "url": "https://earthquake.caseyjhand.com/mcp"
    }
  }
}

自托管 / 本地运行

将以下内容添加到 MCP 客户端配置文件中。

{
  "mcpServers": {
    "earthquake-mcp-server": {
      "type": "stdio",
      "command": "bunx",
      "args": ["@cyanheads/earthquake-mcp-server@latest"],
      "env": {
        "MCP_TRANSPORT_TYPE": "stdio",
        "MCP_LOG_LEVEL": "info"
      }
    }
  }
}

或使用 npx（无需 Bun）：

{
  "mcpServers": {
    "earthquake-mcp-server": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "@cyanheads/earthquake-mcp-server@latest"],
      "env": {
        "MCP_TRANSPORT_TYPE": "stdio",
        "MCP_LOG_LEVEL": "info"
      }
    }
  }
}

或使用 Docker：

{
  "mcpServers": {
    "earthquake-mcp-server": {
      "type": "stdio",
      "command": "docker",
      "args": ["run", "-i", "--rm", "-e", "MCP_TRANSPORT_TYPE=stdio", "ghcr.io/cyanheads/earthquake-mcp-server:latest"]
    }
  }
}

使用 Streamable HTTP 时，设置传输方式并启动服务：

MCP_TRANSPORT_TYPE=http MCP_HTTP_PORT=3010 bun run start:http
# Server listens at http://localhost:3010/mcp

前置条件

• Bun v1.4.0 或更高版本。
• 无需 API 密钥——USGS 和 EMSC 数据完全公开。

安装

1. 克隆代码库：

git clone https://github.com/cyanheads/earthquake-mcp-server.git

2. 进入目录：

cd earthquake-mcp-server

3. 安装依赖项：

bun install

配置

所有配置都会在启动时通过 src/config/server-config.ts 中的 Zod 架构进行验证。主要环境变量：

变量	说明	默认值
MCP_TRANSPORT_TYPE	传输方式：stdio 或 http	stdio
MCP_HTTP_PORT	HTTP 服务端口	3010
MCP_HTTP_ENDPOINT_PATH	MCP 服务挂载的 HTTP 端点路径	/mcp
MCP_PUBLIC_URL	用于 TLS 终止反向代理部署的公共源覆盖值	无
MCP_SESSION_MODE	HTTP 会话：stateful、stateless 或 auto（解析为 stateful）。覆盖 createApp() 声明；Docker 和 .env.example 也固定为 stateless。	stateless（在 src/index.ts 中声明）
MCP_AUTH_MODE	身份验证：none、jwt 或 oauth	none
MCP_LOG_LEVEL	日志级别（debug、info、warning、error 等）	info
MCP_GC_PRESSURE_INTERVAL_MS	选择启用的、仅限 Bun 的强制 GC 压力循环（毫秒）。如果持续 HTTP 负载下观察到堆增长，可尝试设置为 60000。	0（已禁用）
LOGS_DIR	Node.js 和 Bun 的日志文件目录	<project-root>/logs
LOG_TOOL_FAILURE_PAYLOADS	记录失败工具的参数和结果，并按键名进行脱敏。自由格式值中的机密信息仍会保留。	false
LOG_TOOL_FAILURE_PAYLOAD_MAX_BYTES	每条已记录失败载荷的 UTF-8 字节数上限	16384
STORAGE_PROVIDER_TYPE	存储后端：in-memory、filesystem、supabase、cloudflare-kv/r2/d1	in-memory
USGS_BASE_URL	USGS API 基础 URL。可覆盖此值以用于测试或镜像。	https://earthquake.usgs.gov
EMSC_BASE_URL	EMSC API 基础 URL。可覆盖此值以用于测试或镜像。	https://www.seismicportal.eu
DEFAULT_LIMIT	earthquake_search_events 的默认结果数量上限	100
REQUEST_TIMEOUT_MS	每次尝试的 HTTP 超时时间（毫秒）；馈送和搜索请求共用 50 秒总上限。独立事件／计数调用使用此每次尝试的值。	10000
OTEL_ENABLED	启用 OpenTelemetry	false
OTEL_EXPORTER_OTLP_ENDPOINT	跟踪（/v1/traces）和指标（/v1/metrics）的基础 URL；特定信号的端点变量会覆盖此值	无
OTEL_EXPORTER_OTLP_LOGS_ENDPOINT	选择启用的 OTLP 日志端点，按原样使用；基础 URL 不会启用日志	无

空值和未替换的整值 ${…} 占位符将使用默认值。可选覆盖项请参阅 .env.example。

运行服务

本地开发

• 构建并运行生产版本：

  # One-time build
  bun run rebuild
  
  # Run the built server
  bun run start:http
  # or
  bun run start:stdio
  

• 运行检查和测试：

  bun run devcheck  # Lints, formats, type-checks, and more
  bun run test      # Runs the test suite
  

Docker

docker build -t earthquake-mcp-server .
docker run --rm -p 3010:3010 earthquake-mcp-server

Dockerfile 默认使用 HTTP 传输、无状态会话模式，并将日志写入 /var/log/earthquake-mcp-server。默认会安装 OpenTelemetry 对等依赖项；构建时使用 --build-arg OTEL_ENABLED=false 可省略这些依赖项。

项目结构

目录	用途
src/mcp-server/tools	工具定义（*.tool.ts）。USGS 和 EMSC 下共四个工具。
src/mcp-server/resources	馈送、馈送续传和事件资源。
src/services/feed-snapshots.ts	按租户范围保留序列化馈送，并对载荷和元数据进行有界计量。
src/services/usgs	USGS ComCat 服务——GeoJSON 馈送获取器和 FDSN 查询 API 客户端。
src/services/emsc	EMSC SeismicPortal 服务——FDSN 事件搜索和计数端点。
src/config	针对服务的环境变量解析和 Zod 验证。
tests/	单元测试和集成测试，结构与 src/ 对应。

开发指南

开发指南和架构规则请参阅 CLAUDE.md。简而言之：

• 处理器抛出异常，框架负责捕获——工具逻辑中不要使用 try/catch
• 使用 ctx.log 记录日志，使用 ctx.state 存储数据
• 在 createApp() 数组中注册新工具和资源
• 验证上游数据，将其规范化为领域类型，并保留缺失值，而不是凭空编造事实

贡献

欢迎提交问题。提交前请运行检查和测试：

bun run devcheck
bun run test

许可证

本项目采用 Apache 2.0 License。详情请参阅 LICENSE 文件。