seismo-mcp

Let AI assistants process seismic waveforms by chatting — no code, no scripts.

让 AI 助手通过对话处理地震波形——不写代码，不写脚本。

English · 中文

What is this?

seismo-mcp is a bridge between AI assistants (like Claude, Cursor) and the software seismologists actually use: ObsPy, CWP/SU, and SAC.

Normally, to filter a seismogram you open a terminal and type something like sac commands or write a Python script with ObsPy. With seismo-mcp installed, you just tell the AI what you want in plain language, and it calls the right tool for you.

A 30-second example

Install it once. Then, in Claude Desktop:

You: Here's event.sac. Bandpass filter 0.5–2 Hz, remove the mean, then cut −5 to 30 seconds and show me the first trace.

The assistant calls the sac-mcp tools behind the scenes — it reads the header, filters, preprocesses, cuts, and plots — and hands you back the processed file and a plot. You never wrote a line of code.

you: "bandpass 0.5-2 Hz, demean, cut -5 to 30 s, plot"
         │
         ▼  (the assistant decides which tools to call)
   ┌─────────────────────────────────────────┐
   │ seismo-mcp servers (already installed)   │
   │   sac-mcp  →  sac_filter / preprocess /  │
   │               cut / plot                 │
   └─────────────────────────────────────────┘
         │
         ▼  (the server runs the real software)
   SAC / ObsPy / CWP-SU  (your local install)
         │
         ▼
   processed file + plot, handed back to you

Related MCP server: IMAS Codex

Why would I want this?

• For researchers & students — skip the "how do I write this command again?" friction. Describe the processing, get the result.

• For multi-toolchain workflows — ObsPy, SU, and SAC speak different dialects; seismo-mcp gives the assistant one consistent way to reach all three.

• For teaching & demos — show seismology processing live, in plain language, without a screen full of shell commands.

How do I use it?

1. Install one or more servers

Pick only what you need. Each server is independent.

Prerequisite: the relevant software must be installed on your computer (ObsPy is auto-installed by obspy-mcp; CWP-SU, SAC, and the GMT binary must be installed separately). See the install guide for details.

Note: uvx comes from uv — install it with brew install uv (macOS/Linux) if you don't have it. The packages will be on PyPI soon; until then see INSTALL.md for the from-source method.

2. Restart your AI assistant and just ask

After installing, restart Claude Desktop (or your MCP-compatible client). Then describe what you want — the assistant will use the tools automatically.

Example things to say:

• "Read shot.su, how many traces and what's the sample interval?"

• "Bandpass this SAC file 2–10 Hz and plot it."

• "Convert trace.sac to MiniSEED."

• "Apply AGC with a 0.5 s window to gather.su, then sort by offset."

What's inside?

Three independent servers, each wrapping one toolchain:

Who is this for?

• Seismologists who want a faster way to drive their existing tools.

• Students learning seismology — see what each operation does, in plain words.

• Anyone curious about connecting scientific software to AI assistants.

Learn more

• 📖 Install guide — step-by-step setup (ObsPy, CWP-SU, SAC, uv).

• 🛠 Design & technical details — why one server per toolchain, the three wrapping patterns, what gotchas were solved.

• 🔧 Each server's README — full tool tables and examples.

Status

Working and tested against real local installs of ObsPy / CWP-SU / SAC / PyGMT. Four servers, ~28 tools. Feedback and contributions welcome.

License

MIT — see LICENSE.

中文

这是什么？

seismo-mcp 是一座桥，把 AI 助手（Claude、Cursor 等）和地震学家真正在用的 软件连起来：ObsPy、CWP/SU、 SAC。

平时，要处理一个地震波形，你得打开终端敲 sac 命令，或用 ObsPy 写 Python 脚 本。装上 seismo-mcp 后，你只需用大白话告诉 AI 你要什么，它就会替你调用相应 的工具。

一个 30 秒的例子

安装一次。然后在 Claude Desktop 里：

你： 这是 event.sac。带通滤波 0.5–2 Hz，去均值，截取 −5 到 30 秒， 然后画第一道给我看。

助手会在后台调用 sac-mcp 的工具——读头、滤波、预处理、截取、绘图——然后把 处理好的文件和图交给你。你全程没写一行代码。

我为什么要用？

• 研究者和学生——跳过"这个命令怎么写来着"的折腾，描述你要的处理，直接拿 结果。

• 跨工具链的工作流——ObsPy、SU、SAC 各说各的方言；seismo-mcp 给了助手一 个统一的方式触达三者。

• 教学和演示——用大白话现场展示地震处理过程，不用满屏的 shell 命令。

怎么用？

1. 安装你需要的 server（按需，互相独立）

前提： 相应软件需已装在本机（ObsPy 会由 obspy-mcp 自动安装；CWP-SU、 SAC 和 GMT 二进制需自行安装）。详见安装指南。

2. 重启 AI 助手，直接开口

装好后重启 Claude Desktop（或其他支持 MCP 的客户端），然后用大白话描述需求， 助手会自动调用工具。

可以这样说：

• "读一下 shot.su，多少道？采样率多少？"

• "把这个 SAC 文件带通滤波 2–10 Hz，然后画出来。"

• "把 trace.sac 转成 MiniSEED。"

• "对 gather.su 做 0.5 秒窗口的 AGC，然后按 offset 排序。"

里面有什么？

三个独立 server，各封装一个工具链：

想了解更多

• 📖 安装指南 —— 分步设置（ObsPy、CWP-SU、SAC、uv）。

• 🛠 设计与技术细节 —— 为什么一工具链一 server、三种封装模式、解决了哪些坑。

• 🔧 各 server 的 README —— 完整工具表和示例。

状态

已在真实安装的 ObsPy / CWP-SU / SAC / PyGMT 上测试通过。四个 server、约 28 个 工具。欢迎反馈和贡献。

许可证

MIT —— 见 LICENSE。