Content
# seismo-mcp
> **Let AI assistants process seismic waveforms by chatting — no code, no scripts.**
[English](#what-is-this) ·
---
## What is this?
**seismo-mcp** is a bridge between AI assistants (like Claude, Cursor) and
the software seismologists actually use: [ObsPy](https://obspy.org),
[CWP/SU](https://wiki.seismic-unix.org), and [SAC](https://ds.iris.edu/ds/nodes/dmc/software/downloads/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
```
## 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.
| Server | Use it if you work with | Install command |
|---|---|---|
| **obspy-mcp** | ObsPy / general waveform I/O | `claude mcp add obspy -- uvx obspy-mcp` |
| **cwp-su-mcp** | CWP/SU reflection processing | `claude mcp add su -- uvx cwp-su-mcp` |
| **sac-mcp** | SAC waveform analysis | `claude mcp add sac -- uvx sac-mcp` |
| **gmt-mcp** | Maps & plots (PyGMT) | `claude mcp add gmt -- uvx gmt-mcp` |
> **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](docs/INSTALL.md) for details.
>
> **Note:** `uvx` comes from [uv](https://docs.astral.sh/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](docs/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:
| Server | What it can do |
|---|---|
| **[obspy-mcp](packages/obspy-mcp)** | Read any waveform format (SAC/MSEED/SEG-Y…), filter, preprocess, resample, convert formats, plot. |
| **[cwp-su-mcp](packages/cwp-su-mcp)** | Seismic Unix trace ops: read headers, filter, gain (AGC), window, sort, set headers. |
| **[sac-mcp](packages/sac-mcp)** | SAC waveform ops: list headers, preprocess, filter, cut, merge, remove instrument response. |
| **[gmt-mcp](packages/gmt-mcp)** | Maps & plots: basemaps, coastlines, epicenter/station maps, x-y plots, labels. |
## 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](docs/INSTALL.md)** — step-by-step setup (ObsPy, CWP-SU, SAC, uv).
- 🛠 **[Design & technical details](docs/DESIGN.md)** — why one server per
toolchain, the three wrapping patterns, what gotchas were solved.
- 🔧 **[Each server's README](packages/)** — 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](LICENSE).
---
