ObsPy MCP
具有LLM驱动分析的模块化地震学研究服务器（MCP+ObsPy+Gemini/AAzure就绪）
与加州大学伯克利分校合作的项目
ObsPy MCP是一个以生产为重点的地震学研究工具包，它结合了：
- ObsPy 用于波形采集+处理
- FDSN网络服务 （虹膜/超声心动图/肌电图）
- MCP（模型上下文协议） 暴露确定性“工具”
- 法学硕士研究代理 （现在支持Gemini；Azure OpenAI就绪）
设计目标很简单： 可重复、可审计的地震研究 LLM可以提供帮助 *规划和解释* 然而 服务器保持确定性 用于下载+处理。
______________________________________________________________________
主要特点
数据发现+下载
- 按震级/时间/地区搜索最近的地震
- 查找附近的电台（网络/电台/频道过滤器）
- 下载波形（MiniSEED）和台站元数据（StationXML）
- 下载前的安全验证（时间窗口、大小限制、通道健全性）
处理+分析
- 下跌/失败者
- 带通滤波器（可配置）
- 删除仪器响应（需要StationXML“响应”级别）
- 快速P拣选（基本拣选器）
- 信噪比估计实用程序
- 绘制波形快速浏览
LLM驱动的援助
- Agent选择一个事件，选择站点，下载数据，处理它
- Agent对观察到的相位进行科学解释
- 供应商选择+旋钮，实现可靠性和成本控制
______________________________________________________________________
项目结构
obspy-mcp/
├── agent/
│ ├── __init__.py
│ └── gemini_agent.py # Gemini-powered research agent (end-to-end workflow)
│
├── server/
│ ├── __init__.py
│ ├── server.py # MCP server entry point
│ ├── tools.py # Tool implementations + safe JSON results
│ ├── fdsn.py # ObsPy FDSN client wrappers
│ ├── validate.py # Validation / estimation helpers for waveform requests
│ ├── limits.py # Safety + usability knobs (rate/size/time limits)
│ ├── picking.py # Simple phase picking helpers
│ ├── snr.py # Signal-to-noise estimates
│ ├── plotting.py # Plotting utilities (PNG quicklook)
│ ├── response_utils.py # Pre-filter recommendations for response removal
│ └── config.py # Central settings (env-configurable)
│
├── data/ # Download outputs (ignored by git)
│ ├── waveforms_*.mseed
│ ├── stations_*.stationxml
│ ├── processed_*.mseed
│ └── processed_*.png
│
├── .env.example
├── .gitignore
├── README.md
└── requirements.txt______________________________________________________________________
数据保存位置
所有下载和输出都写入：
data/
示例：
- 波形：
data/waveforms_.mseed - Station XML：
data/stations_.stationxml - 处理：
data/processed_.mseed - 快速浏览图：
data/processed_.png
data/应该留下来 忽略 在.gitignore.
______________________________________________________________________
需求
- python 3.11+ 强烈推荐
- 支持macOS/Linux/Windows（macOS最简单）
______________________________________________________________________
安装（VS代码友好）
1） 克隆仓库
git clone https://github.com/Fahim-Azwad/obspy-mcp.git
cd obspy-mcp2） 创建并激活虚拟环境
macOS/Linux：
python3.11 -m venv .venv
source .venv/bin/activateWindows（PowerShell）：
py -3.11 -m venv .venv
.venv\Scripts\Activate.ps13） 安装依赖项
python -m pip install --upgrade pip
pip install -r requirements.txt4） 在VS Code中选择解释器
打开命令选项板→ Python: Select Interpreter
选择： .../obspy-mcp/.venv/bin/python
______________________________________________________________________
配置
Gemini（推荐默认值）
推荐： 使用本地 .env 文件（由代理自动加载）。
cp .env.example .env然后编辑 .env 并且至少设置：
GOOGLE_API_KEY=...（首选）
- 或 GEMINI_API_KEY=...
可选覆盖：
GEMINI_MODEL=models/gemini-2.5-flash（默认）GEMINI_FALLBACK_MODEL=models/gemini-2.5-proFDSN_PROVIDER=IRIS
您还可以在shell中导出env变量，而不是使用 .env.
Azure OpenAI（可选/面向未来）
这些是虚拟占位符（不提交真实密钥）：
export AZURE_ENDPOINT="https://xxx.openai.azure.com/"
export AZURE_API_KEY="xxx"
export DEPLOYMENT_NAME="gpt-5-chat"______________________________________________________________________
跑步
运行MCP服务器（手动）
这将启动工具服务器（stdio MCP）。它主要由代理人使用。
python -m server.server注： 如果手动运行服务器，它将在stdin上等待MCP JSON-RPC消息（因此可能会出现“卡住”）。这很正常。
运行Gemini Research Agent（推荐）
python -m agent.gemini_agent -p "Find a recent magnitude 7+ earthquake and analyze BH? waveforms."提示提示（最大限度地提高自动化程度）
代理是确定性的，但它可以提取一些 简单提示 从 --prompt 要覆盖默认值，请执行以下操作：
- 最小震级:
M7+,M6.5+,magnitude >= 7 - 事件回顾窗口:
last 30 days,past 2 weeks,last 3 months - 车站搜索半径:
within 3°,within 300 km,radius 5 degrees
如果没有提示，默认值为： M7+, 过去90天, 2°以内.
复制/粘贴示例：
# Smaller events, shorter window (faster searches)
python -m agent.gemini_agent -p "Find M6.5+ earthquakes in the last 14 days and use stations within 250 km"
# Wider station search if you frequently get HTTP 204 (no data)
python -m agent.gemini_agent -p "Find M7+ earthquakes in the last 60 days and use stations within 5°"
# Very large events with broader window
python -m agent.gemini_agent -p "Find M8+ earthquakes in the last 6 months and use stations within 3°"提示：一个好的提示通常包括（1）事件约束，（2）站半径，以及（3）您想要解释的内容（例如，P与S到达、表面波、滤波、响应去除）。
您可以选择在提示中包含简单的提示来覆盖默认值：
python -m agent.gemini_agent -p "Find M6.5+ earthquakes in the last 30 days and use stations within 3°"支持的提示模式（不区分大小写）： M7+, last 30 days / past 2 weeks, within 300 km / within 3°.
可选：
python -m agent.gemini_agent -p "..." --provider IRIS代理人将：
- 查找最近的大型事件（默认值：过去90天，$M\\ge7$）
- 查找活动周围的附近宽带站（BH？）（默认半径2°）
- 下载波形+StationXML
- 过程和绘图结果
- 输出科学解释
______________________________________________________________________
MCP代理如何获取数据
代理人是 不 刮网器。它在本地启动MCP服务器（stdio传输）并调用确定性MCP工具。
此版本中的管道：
- 启动MCP服务器：
python -m server.server - 通过查找工具列表
list_tools - 获取最近的大型事件（过去90天，$M\\ge7$）
- 使用以下工具搜索2°以内的站点
BH? - 使用验证波形请求
validate_only - 下载波形+StationXML
- 跑
full_process生成处理后的MiniSEED+PNG快速浏览 - 向双子座求婚 科学解释 由此产生的伪影
注： --prompt 文本目前主要用于 最后解释事件/站点选择遵循上述确定性默认值。
更新： --prompt 也可以覆盖 最小震级, 事件回顾窗口，以及 车站半径 当你包含简单的提示短语时（见上面的“提示提示”）。其他选择（频道 BH?、波形窗口、处理步骤）保持确定性默认值。
______________________________________________________________________
MCP工具
这些由服务器通过MCP公开：
| 工具 | 说明 |
|---|---|
search_events | 按时间窗、震级、界限查找地震 |
search_stations | 根据半径或边界、通道模式查找站点 |
validate_only | 下载前验证+估计波形请求 |
download_waveforms | 安全下载波形（MiniSEED） |
download_stations | 下载StationXML以删除响应 |
full_process | 下跌趋势→ 过滤器→ 删除响应→ pick → 情节 |
所有工具都返回严格的JSON。错误返回JSON ok=false 加上可读的消息。
______________________________________________________________________
安全+可用性旋钮
服务器强制设置安全护栏（可在中配置 server/limits.py 和env变量）：
- 每次请求的最大持续时间（秒）
- 通道/迹线的最大数量
- 最大总样本数/估计字节数
- 提供商回退处理（IRIS/USGS/EMSC）
- 仅验证模式，用于在下载前估算成本/大小
这些可以防止意外的“下载整个互联网”请求。
______________________________________________________________________
输出示例
典型的工作流程会生成以下工件：
{
"ok": true,
"file": "data/processed_cc665600ea6c.mseed",
"plot": "data/processed_cc665600ea6c.png",
"picks": {
"II.ERM.00.BHZ": "2025-12-08T14:10:30.44"
}
}您可以在本地打开PNG图以直观地检查跟踪。
______________________________________________________________________
故障排除
“pip：找不到命令”
用途：
python -m pip install -r requirements.txt“python：找不到命令”
在macOS上，首选：
python3 --version
python3 -m pip --version服务器似乎卡住了
如果你直接运行它，这是意料之中的。它等待MCP消息。 请运行代理：
python -m agent.gemini_agent未返回数据（HTTP 204）
该请求窗口或站/信道可能没有波形覆盖。 尝试：
- 另一个车站
- 更大的半径
- 不同的信道码（例如。，
HH?对比BH?) - 时间窗口稍长
______________________________________________________________________
路线图（下一步改进）
建议的后续步骤（生产硬化）：
- \[\]研究CLI（菜单驱动）：用户选择事件/站/下载选项
- \[\]理论相位到达预测的TauP积分
- \[\]更好的电台排名：
- 距离 - 车站正常运行时间 - 估计信噪比
- \[\]多站下载+对齐绘图
- \[\]Dockerfile+单命令部署
- \[\]Azure OpenAI代理奇偶校验（可选）
______________________________________________________________________
许可证
麻省理工学院——免费用于研究和商业用途。
______________________________________________________________________
作者
S M Azwad Ul Alam\ 地震学•人工智能系统•研究基础设施
应要求建造的项目 朱伟强教授，加州大学伯克利分校地球与行星科学系