mcp-fdsnws-event

FDSNWS Event MCP Server

An MCP (Model Context Protocol) server for querying the FDSN Web Service Event APIs of multiple seismological datacenters (INGV, EMSC, GFZ, USGS, etc.) and retrieving earthquake information as JSON.

Features

• Multi-datacenter: works with any FDSN-compliant datacenter (INGV, EMSC, GFZ, USGS, and others)
• 8 MCP tools: event search, single-event detail, arrivals, station magnitudes, amplitudes, magnitudes, origins, focal mechanisms
• Two output shapes: station-level collections (arrivals, station magnitudes, amplitudes, event lists) come back as a paginated table (columns + rows); solution-level objects (event, origins, magnitudes, focal mechanisms) come back as full QuakeML→JSON detail
• Context-budgeted: every result is bounded in bytes so a single tool call cannot push the user's own question out of an LLM's context window
• stdio transport: JSON-RPC 2.0 over stdin/stdout
• Containerized: ready to use with Docker

Upgrading from 1.x? Release 2.0.0 renames every event-keyed tool and changes the response shape of three of them. See Breaking changes in 2.0.0.

Installation

Prerequisites

• Docker
• Python 3.11+ (for local development)

Option A: Pull from Docker Hub (recommended)

Prebuilt multi-arch images (linux/amd64, linux/arm64) are published on Docker Hub:

# Latest release
docker pull ingv/mcp-fdsnws-event:latest

# A specific version (replace X.Y.Z with a published tag)
docker pull ingv/mcp-fdsnws-event:X.Y.Z

An mcpo variant (OpenAPI/REST wrapper, see below) is published under the same repository with a -mcpo suffix, e.g. ingv/mcp-fdsnws-event:latest-mcpo and ingv/mcp-fdsnws-event:X.Y.Z-mcpo.

Option B: Build the container locally

# Clone the repository
git clone https://github.com/INGV/mcp-fdsnws-event.git
cd mcp-fdsnws-event

# Build the Docker image
docker build --no-cache -t ingv/mcp-fdsnws-event .

Usage

Start the MCP server

# Pull the published image (first run only)
docker pull ingv/mcp-fdsnws-event

# Start the MCP server (stdio)
docker run -i --rm ingv/mcp-fdsnws-event

The server listens for MCP connections over stdio.

Testing

# Full unified test suite (recommended)
./run_tests.sh

# Individual runs (if needed)
# Unit tests (offline)
docker run --rm ingv/mcp-fdsnws-event pytest

# MCP protocol smoke test
echo -e '{"jsonrpc": "2.0", "id": 1, "method": "initialize", "params": {"protocolVersion": "2024-11-05", "capabilities": {}, "clientInfo": {"name": "test", "version": "1.0.0"}}}\n{"jsonrpc": "2.0", "method": "notifications/initialized", "params": {}}\n{"jsonrpc": "2.0", "id": 2, "method": "tools/list", "params": {}}' | docker run -i --rm mcp-fdsnws-event-server

run_tests.sh automatically runs:

1. Docker image build
2. Unit tests (offline)
3. MCP protocol smoke test

To also run the live tests against INGV: ./run_tests.sh --integration. This is the recommended way to validate all functionality.

Available tools

The server exposes 8 tools. They all accept an optional datacenter parameter (default: "INGV"). Supported datacenters: INGV, EMSC, GFZ, USGS, and other FDSN-compliant services.

Tool	Returns	Shape
fdsn_query_earthquakes	one row per event, preferred origin and magnitude	table
fdsn_get_earthquake_by_eventid	event, preferred origin, preferred magnitude, focal mechanisms, counts	QuakeML detail
fdsn_get_arrivals_by_eventid	phase arrivals, each joined with its pick	table
fdsn_get_allorigins_by_eventid	all origin solutions	QuakeML detail
fdsn_get_allmagnitudes_by_eventid	all magnitude solutions	QuakeML detail
fdsn_get_focalmechanism_by_eventid	focal mechanisms and moment tensors	QuakeML detail
fdsn_get_stationmagnitudes_by_eventid	per-station magnitude readings, each joined with its amplitude	table
fdsn_get_amplitudes_by_eventid	measured amplitudes	table

Note on IRIS. IRIS/EarthScope no longer serves the FDSNWS event service: both service.iris.edu and service.earthscope.org answer /fdsnws/event/1/query with HTTP 410 Gone. It is therefore no longer advertised here; USGS is the recommended global substitute. Station and waveform services at EarthScope are unaffected (this server does not use them).

Table responses

Station-level collections have one entry per station reading, and an event can carry thousands of them. Serialized as a list of QuakeML objects they overflow an LLM context window on their own, so the four tools marked table above return a tabular payload instead: the field names are stated once in columns, and rows carries one list of values per record, in the same order. The column set is fixed per tool and always complete — a field the datacenter does not populate comes back as null rather than disappearing — so the shape does not change from one datacenter to the next.

Identifiers are split in two. QuakeML identifiers are URIs of which almost every character is boilerplate repeated on every row, so the envelope carries an id_prefixes map from column name to the prefix shared by that column's values, and the rows carry only the remainder. The full identifier is the concatenation, character for character:

{
  "id_prefixes": {
    "pick_id": "smi:webservices.ingv.it/fdsnws/event/1/query?pickId="
  },
  "columns": ["arrival_id", "pick_id", "phase", "..."],
  "rows": [["...", "817336441", "Pg", "..."]]
}

so the pick_id of that row is smi:webservices.ingv.it/fdsnws/event/1/query?pickId=817336441. A column with no worthwhile shared prefix is simply absent from the map and its rows already hold the complete value. Nothing is dropped: this is an encoding, not a summary.

Pagination. Every table takes limit and offset (1-based) and answers with returned_count, has_more and, when there is more, next_offset. Page by resending the same call with offset: next_offset until has_more is false. returned_count can come back below the limit asked for: the byte budget described under Configuration shrinks a page that would not fit rather than failing the call, and next_offset still lines up. The three event-keyed tables also report total_count, the number of rows matching the query once the filters below have been applied, next to a <resource>_count (arrivals_count, station_magnitudes_count, amplitudes_count) giving the size of the event's whole collection regardless of any filter — which is how an empty page saying "this event has none at all" is told apart from one saying "your filters matched none".

Filters. The three event-keyed tables accept network and station (exact, case-insensitive), and the station-magnitude table also accepts magnitude_type. They are applied by this server after the fetch, because no FDSN event service filters a sub-resource by station; they exist so that "the amplitude at station SGRT" costs one small answer instead of paging through every reading of the event.

Every origin, not just the preferred one. Arrival rows and station-magnitude rows span every origin the datacenter returned for the event, with origin_id naming the origin and is_preferred_origin marking the rows of the preferred solution, which are also sorted first. Filtering to the preferred origin would be invisible data loss: an EMSC event comes back with six origins carrying 137 preferred arrivals and 137 more elsewhere, while on INGV every arrival already sits on the preferred origin and the rule costs nothing. The envelope reports origins_count so the difference between datacenters is visible rather than hidden. Amplitudes belong to the event rather than to an origin in QuakeML, so they carry no origin_id.

1. fdsn_query_earthquakes

Search seismic events with flexible filters. With no parameters it returns today's events.

Parameters (all optional):

• starttime / endtime: time window (ISO format: YYYY-MM-DDTHH:MM:SS). Default: today 00:00:00–23:59:59 UTC
• updatedafter: only events updated after this date/time
• minmag / maxmag: magnitude range
• mindepth / maxdepth: depth range (in km, the FDSN query-parameter unit)
• minlat / maxlat / minlon / maxlon: geographic bounding box
• latitude / longitude / minradiuskm / maxradiuskm: radial search
• limit: maximum number of events (default: 100, max: 240 — both configurable, see Configuration)
• offset: 1-based index of the first event (default: 1), to paginate together with limit
• orderby: sort order — time (default, most recent first), time-asc, magnitude, magnitude-asc
• datacenter: FDSN datacenter to query (default: "INGV", overridable)

Note: the bounding-box parameters and the radial-search parameters are mutually exclusive.

Output: a table (columns + rows, one row per event with the preferred origin and magnitude; depth in km). returned_count, limit, offset, has_more and next_offset sit at the top level of the response, next to a query echo of the parameters actually sent upstream. The column names are normalised to the fourteen names of the FDSN 1.2 text profile (event_id, time, latitude, longitude, depth_km, author, catalog, contributor, contributor_id, mag_type, magnitude, mag_author, location_name, event_type), because the datacenters spell their own header differently — INGV writes Depth/Km, EMSC, GFZ and USGS write Depth/km, and EventType is absent from EMSC and USGS entirely — and a column name that depends on who answered is not something a client can be written against. An unrecognised column is lowercased and passed through rather than dropped.

Unlike the event-keyed tables this one has no total_count: FDSN text carries no count, so has_more is inferred from the page having been filled exactly. For the detail of a single event use the *_by_eventid tools.

Examples:

// Today's events (default)
{}

// Significant events (M>=4.0) over the last week
{"minmag": 4.0, "starttime": "2025-07-08T00:00:00", "limit": 50}

// Specific geographic area (Central Italy)
{"minlat": 41.0, "maxlat": 43.0, "minlon": 12.0, "maxlon": 15.0, "minmag": 2.0}

// Radial search (50 km around Rome)
{"latitude": 41.9, "longitude": 12.5, "maxradiuskm": 50}

// Query USGS instead of INGV
{"minmag": 5.0, "starttime": "2025-01-01T00:00:00", "datacenter": "USGS"}

2. fdsn_get_earthquake_by_eventid

Returns the core information for a single event: the event metadata, the preferred origin, the preferred magnitude and the focal mechanisms, as full QuakeML detail. Note that the preferred magnitude does not always belong to the preferred origin — on INGV event 46107472 the preferred Mw 6.1 hangs off one origin while the preferred origin carries an ML 6.2 — so preferred_origin_id and preferred_magnitude_id are both reported explicitly.

Station-level collections are no longer inlined. Picks, amplitudes and station magnitudes used to be serialized into this response, which is what made it the largest answer this server could produce: 3510 kB for one INGV Mw 6.1 event, of which 1886 kB was amplitudes alone. They now live in dedicated tools, and this response reports station_magnitudes_count and amplitudes_count so a caller knows whether there is anything to fetch. There is deliberately no arrivals_count: this fetch does not send includearrivals, so every origin comes back with an empty arrival list, and a count taken from it would read as a confident "this event has no phases" — ask fdsn_get_arrivals_by_eventid, which does know.

Parameters:

• eventid (required): event identifier, as returned by fdsn_query_earthquakes in the event_id column. Treated as an opaque string matching ^[A-Za-z0-9_.:-]+$, so the differing conventions of the providers are all accepted (45376822 at INGV, 20240101_0000328 at EMSC, gfz2024abmz at GFZ, us6000m0yg at USGS). A JSON integer is still accepted and normalised.
• datacenter (optional): default "INGV"

3. fdsn_get_arrivals_by_eventid

Returns the seismic phase arrivals of an event as a table, each row joined with the pick it associates (station, time, phase, residual). Useful to know which stations recorded the event and what was read on them.

Rows are ordered by distance from the hypocentre when the datacenter provides it — the order a seismologist reads a phase list in — and by pick time otherwise, with the preferred-origin rows first either way; ordered_by in the response says which was used.

Parameters:

• eventid (required): opaque event identifier, as described for fdsn_get_earthquake_by_eventid above.
• datacenter (optional): default "INGV"
• network / station (optional): exact, case-insensitive row filters
• limit (optional): default 90, max 90 (configurable)
• offset (optional): 1-based, default 1

4. fdsn_get_allorigins_by_eventid

Returns all origin solutions (hypocentre locations) for an event, indicating which one is preferred. Useful to compare locations computed by different agencies.

Parameters:

• eventid (required): opaque event identifier, as described for fdsn_get_earthquake_by_eventid above.
• datacenter (optional): default "INGV"

5. fdsn_get_allmagnitudes_by_eventid

Returns all magnitude solutions computed for an event (ML, Mw, Mb, Md, etc.), indicating which one is preferred. Useful for comparing magnitude types or agencies. For the per-station readings behind a magnitude use fdsn_get_stationmagnitudes_by_eventid.

Parameters:

• eventid (required): opaque event identifier, as described for fdsn_get_earthquake_by_eventid above.
• datacenter (optional): default "INGV"

6. fdsn_get_focalmechanism_by_eventid

Returns the focal mechanisms and moment tensors for an event: nodal planes (strike, dip, rake), principal axes (T, P, N), and moment tensor components.

Parameters:

• eventid (required): opaque event identifier, as described for fdsn_get_earthquake_by_eventid above.
• datacenter (optional): default "INGV"

7. fdsn_get_stationmagnitudes_by_eventid

Returns the per-station magnitude readings of an event as a table, each row joined with the amplitude it was computed from. Useful when asked which stations contributed to a magnitude, or for the magnitude measured at one station.

A station magnitude belongs to an origin, given by origin_id; where an origin carries more than one magnitude, station_magnitude_type tells the readings apart and can be filtered on. Rows are ordered by network, station and channel. Not every datacenter publishes these: an empty table with a message means the event exists but carries none.

Parameters:

• eventid (required): opaque event identifier, as described for fdsn_get_earthquake_by_eventid above.
• datacenter (optional): default "INGV"
• network / station (optional): exact, case-insensitive row filters
• magnitude_type (optional): exact, case-insensitive filter on station_magnitude_type
• limit (optional): default 200, max 220 (configurable)
• offset (optional): 1-based, default 1

8. fdsn_get_amplitudes_by_eventid

Returns the measured amplitudes of an event as a table: value, unit, period, signal-to-noise ratio, time window and station. Useful when asked what was recorded, or for the amplitude measured at one station.

In QuakeML an amplitude belongs to the event rather than to an origin, so all of them are returned and many are not referenced by any station magnitude — of the 2152 amplitudes on the INGV event measured, only 677 were. Rows are ordered by network, station and channel. Not every datacenter publishes them: an empty table with a message means the event exists but carries none.

Parameters:

• eventid (required): opaque event identifier, as described for fdsn_get_earthquake_by_eventid above.
• datacenter (optional): default "INGV"
• network / station (optional): exact, case-insensitive row filters
• limit (optional): default 125, max 125 (configurable)
• offset (optional): 1-based, default 1

MCP client configuration

To use this server with an MCP client (such as Claude Desktop), add the following configuration:

{
  "mcpServers": {
    "fdsnws-event": {
      "command": "docker",
      "args": ["run", "-i", "--rm", "ingv/mcp-fdsnws-event"]
    }
  }
}

To tune the server from here, pass the variables as -e flags among the args; see Configuration for why the client's env key does not reach the container.

Configuration

The server is configured entirely through environment variables. There is no configuration file and nothing is read from a .env file inside the process: the variables have to be present in the container's environment.

Variable	Default	Effect
FDSN_TIMEOUT	45	Timeout in seconds for a request to the datacenter. Read per call
FDSN_MAX_RESULT_BYTES	36000	Byte budget for a single tool result
FDSN_MAX_ROWS_ARRIVALS	90	Largest limit accepted by fdsn_get_arrivals_by_eventid
FDSN_DEFAULT_ROWS_ARRIVALS	90	limit used when the caller does not give one
FDSN_MAX_ROWS_STATIONMAGNITUDES	220	Largest limit accepted by fdsn_get_stationmagnitudes_by_eventid
FDSN_DEFAULT_ROWS_STATIONMAGNITUDES	200	limit used when the caller does not give one
FDSN_MAX_ROWS_AMPLITUDES	125	Largest limit accepted by fdsn_get_amplitudes_by_eventid
FDSN_DEFAULT_ROWS_AMPLITUDES	125	limit used when the caller does not give one
FDSN_MAX_ROWS_EVENTS	240	Largest limit accepted by fdsn_query_earthquakes
FDSN_DEFAULT_ROWS_EVENTS	100	limit used when the caller does not give one

.env.example lists the same set, ready to copy to .env and pass with --env-file.

Where the numbers come from. FDSN_MAX_RESULT_BYTES is a context budget rather than a storage limit, and both halves of the derivation are measured rather than assumed. The density of this JSON is 1.87 bytes per token: the slope of prompt_eval_count against payload size measured on qwen3.8:27b under Ollama, 1511 bytes costing 476 tokens and 48 667 costing 25 744, linear in between. At that density 36 000 bytes is about 19 250 tokens, 59% of a 32k context window, leaving the rest for the conversation the result has to live inside. Each table's maximum is then that budget divided by the widest row the finished tool actually emitted against INGV, EMSC, GFZ and USGS — 391 B/row for arrivals (GFZ, whose opaque identifiers share almost no prefix to lift out), 159 for station magnitudes, 279 for amplitudes, 149 for events. The byte budget is the backstop underneath the row limits, not the first line of defence: on a table it shrinks the page and sets has_more, so the call still succeeds; on a solution-level object, which cannot be split, it returns a structured error naming the size and pointing at the table tools.

These figures are calibrated for a 32k window, because that is the window of the deployment this release was written for. A larger window is exactly what these variables are there to be raised for: the numbers are policy, not a property of the data.

Two things to know before changing a MAX_ROWS_*. They are read once at import, because each one is published as the maximum of that tool's limit parameter in the JSON schema this server advertises in tools/list — they are not only what the server honours but what the model is told it may ask for. So the container must be restarted for a change to take effect, and any client that caches the tool schema has to be refreshed too: behind mcpo the OpenAPI spec is generated at startup, so an Open WebUI tool server must be re-imported before the new maximum is visible. A value that is not a positive integer is ignored with a warning and the default is used; a DEFAULT_ROWS_* above its own MAX_ROWS_* is clamped down with a warning rather than taking the server down on a config typo.

Setting the variables

1. Plain docker run — how a stdio deployment normally runs:

docker run -i --rm \
  -e FDSN_TIMEOUT=60 \
  -e FDSN_MAX_ROWS_ARRIVALS=90 \
  ingv/mcp-fdsnws-event

# or, once repeating -e flags gets unwieldy
cp .env.example .env    # then edit
docker run -i --rm --env-file .env ingv/mcp-fdsnws-event

2. The mcpServers JSON of an MCP client. Mind the trap here: the env key of an mcpServers entry sets the environment of the process the client spawns, which is the docker binary — not the container it starts. Docker does not forward its own environment into the container, so a variable placed in env silently has no effect. It has to be carried in explicitly with -e NAME=value among the args:

{
  "mcpServers": {
    "fdsnws-event": {
      "command": "docker",
      "args": [
        "run", "-i", "--rm",
        "-e", "FDSN_MAX_RESULT_BYTES=36000",
        "-e", "FDSN_MAX_ROWS_ARRIVALS=90",
        "ingv/mcp-fdsnws-event"
      ]
    }
  }
}

(The env key is still the right place for variables meant for the docker client itself, such as DOCKER_HOST.)

3. Compose. Both compose.yml and compose.mcpo.yml carry an environment: block listing the whole set, commented out at its default; uncomment what you want to change. The mcpo image runs the server as a child process inside the container, so there is no docker binary in between and environment: — or docker run -e on that image — reaches the server directly.

Breaking changes in 2.0.0

Release 2.0.0 changes the tool surface. Every mcpo and Open WebUI registration has to be refreshed, because the callable names change: in Open WebUI the generated names become tool_fdsn_get_arrivals_by_eventid_post and so on, and a tool server imported before the upgrade keeps advertising names that no longer exist.

Tools renamed. Every tool that takes an event identifier is now named _by_eventid, after the input the caller must supply rather than after the QuakeML class the data comes from. Naming a tool for a class it cannot be queried by — arrivals belong to an origin, but no FDSN node accepts an origin id — invites a model to invent an identifier, which is the exact failure this server already guards against elsewhere.

1.x	2.0.0
fdsn_get_earthquake_by_id	fdsn_get_earthquake_by_eventid
fdsn_get_arrivals_by_id	fdsn_get_arrivals_by_eventid
fdsn_get_allorigins_by_id	fdsn_get_allorigins_by_eventid
fdsn_get_allmagnitudes_by_id	fdsn_get_allmagnitudes_by_eventid
fdsn_get_focalmechanism_by_id	fdsn_get_focalmechanism_by_eventid
—	fdsn_get_stationmagnitudes_by_eventid (new)
—	fdsn_get_amplitudes_by_eventid (new)

fdsn_query_earthquakes keeps its name.

Response shape. fdsn_get_arrivals_by_eventid no longer returns a list of QuakeML objects: it returns columns + rows + id_prefixes with limit/offset pagination, like the two new tools. Callers that walked an arrivals array must be rewritten against the table.

Flattened envelope on fdsn_query_earthquakes. returned_count, limit, offset, has_more and next_offset are now top-level keys of the response instead of a nested pagination object, so all four tables share the same pagination keys.

Normalized event column names. fdsn_query_earthquakes no longer passes the datacenter's own text header through. Columns are mapped to the FDSN 1.2 names, so Depth/Km (INGV) and Depth/km (EMSC, GFZ, USGS) both become depth_km, EventID becomes event_id, EventLocationName becomes location_name, and so on. Code that indexed the header by its INGV spelling must be updated.

No more station-level collections in fdsn_get_earthquake_by_eventid. Picks, amplitudes and station magnitudes are gone from that response; use the dedicated tools. station_magnitudes_count and amplitudes_count are reported so you know whether to ask.

Example queries

Today's events

"Show me today's earthquakes in Italy"

Significant events

"What were the strongest earthquakes of the last week?"

Events in a specific region

"Find earthquakes with magnitude above 3.0 in central Italy over the last 30 days"

Development

Project structure

mcp-fdsnws-event/
├── src/fdsnws_event_server/
│   ├── __init__.py
│   ├── server.py          # MCP server (FastMCP tool definitions)
│   ├── models.py          # Pydantic input validation models
│   ├── config.py          # Env-driven limits (byte budget, row maxima/defaults)
│   ├── tables.py          # Tabular serialization: columns, rows, id prefixes, paging
│   └── obspy_client.py    # FDSN format=text query + ObsPy QuakeML→JSON detail
├── tests/                 # pytest: unit (offline) + integration (live)
│   ├── fixtures/          # Real FDSN format=text responses
│   ├── unit/              # Parser, query, models (network mocked)
│   ├── integration/       # Live INGV tests (@pytest.mark.integration)
│   └── README.md          # How to run the tests
├── pyproject.toml         # Python configuration
├── Dockerfile             # Docker container
├── run_tests.sh           # Full test suite
└── README.md

Local testing

# Install dependencies (with dev extras for pytest)
pip install -e ".[dev]"

# Run the tests
pytest                 # unit (offline, default)
pytest -m integration  # live tests against INGV (network required)

Test details and conventions in tests/README.md.

FDSN API

The server queries any FDSN-compliant datacenter:

• INGV (default): https://webservices.ingv.it/fdsnws/event/1/query
• EMSC: https://www.seismicportal.eu/fdsnws/event/1/query
• GFZ: https://geofon.gfz.de/fdsnws/event/1/query
• USGS: https://earthquake.usgs.gov/fdsnws/event/1/query
• Format: search via format=text (tabular); detail via QuakeML (XML) → JSON
• Documentation: FDSNWS Event API

OpenWebUI integration (mcpo)

OpenWebUI talks to MCP servers through mcpo, a proxy that exposes an MCP server as an OpenAPI/REST endpoint. This repository ships an mcpo wrapper that runs the server directly (no docker-in-docker, no Docker socket mount): see Dockerfile.mcpo and compose.mcpo.yml.

Run

Pull and run the published mcpo image (recommended):

docker pull ingv/mcp-fdsnws-event:latest-mcpo
docker run -d -p 8000:8000 --name mcp-fdsnws-event_mcpo ingv/mcp-fdsnws-event:latest-mcpo

Or build it locally (for development):

docker build -t ingv/mcp-fdsnws-event .              # base image
docker compose -f compose.mcpo.yml up -d --build     # mcpo wrapper on :8000

This exposes:

• OpenAPI spec: http://<host>:8000/openapi.json
• Swagger UI: http://<host>:8000/docs
• One endpoint per tool, e.g. POST http://<host>:8000/fdsn_query_earthquakes

Connect OpenWebUI

In OpenWebUI go to Settings → Integrations (or for all users, Admin Panel → Settings → Integrations) and add a new "Tool Server" with the URL http://<host>:8000.

• If OpenWebUI itself runs in Docker, localhost:8000 from inside its container will not reach the host. Use http://host.docker.internal:8000 (Docker Desktop) or the host LAN IP, or put both services on the same Docker network.
• Securing the endpoint: by default mcpo is exposed without authentication. To protect it, uncomment the command: line in compose.mcpo.yml to add --api-key "<your-key>", then set the same key in OpenWebUI.

compose.mcpo.yml is a development configuration, not a hardened one. It binds 0.0.0.0:8000 and publishes the port on every host interface, with authentication commented out, no rate limiting and no bound on concurrent upstream requests. That is fine on a workstation or inside a trusted network; it is not a public service. Exposing it beyond a trusted network means at minimum binding to 127.0.0.1 behind a reverse proxy that terminates TLS and enforces authentication and rate limits. Note that these are properties of the deployment rather than of the MCP server, which is read-only, stateless and holds no credentials — in stdio mode it opens no port at all.

The wrapper image bundles mcpo and the server in a single image and runs mcpo ... -- python -m fdsnws_event_server.server, so it does not mount the Docker socket or spawn nested containers.

Validating tool-call reliability (A/B harness)

When a client model loses an identifier across turns it may invent one — e.g. calling fdsn_get_arrivals_by_eventid with a placeholder eventid (123456) instead of the event_id returned by a prior fdsn_query_earthquakes. The server guards against this with a three-state by-eventid contract (found / message), but the behaviour itself lives in the OpenWebUI ↔ model loop and is best measured empirically.

tests/ab/eventid_hallucination_ab.py is a standalone A/B harness (not run by pytest) that replays the failing conversation against a live model through the OpenWebUI OpenAI-compatible API and reports how often the model passes the correct eventid vs an invented one. It takes the model and base URL as arguments:

export OPENWEBUI_API_KEY=sk-...        # OpenWebUI: Settings → Account → API Keys
python tests/ab/eventid_hallucination_ab.py \
    --base-url http://<host>:8080 \
    --model <model-id-as-listed-in-openwebui> \
    --repeat 10 --variant both --temperature 0.7

It fails fast if --model is not present on the instance, and compares two tool descriptions (baseline vs fixed) so you can attribute any delta to the server-side wording. Use it to check a new model, or to confirm that an OpenWebUI configuration change (e.g. Native function calling) actually fixes id reuse.

Citation

If you use this software in your research, please cite the accompanying paper, published open access (CC BY 4.0) in SoftwareX:

Lauciani, V., & Bailo, D. (2026). mcp-fdsnws-event: An MCP gateway for FDSNWS-event web services. SoftwareX, 35, 103001. https://doi.org/10.1016/j.softx.2026.103001

@article{lauciani2026mcpfdsnwsevent,
  title   = {mcp-fdsnws-event: An MCP gateway for FDSNWS-event web services},
  author  = {Lauciani, Valentino and Bailo, Daniele},
  journal = {SoftwareX},
  volume  = {35},
  pages   = {103001},
  year    = {2026},
  issn    = {2352-7110},
  doi     = {10.1016/j.softx.2026.103001}
}

A CITATION.cff file is also provided, so GitHub can generate the citation in APA or BibTeX from the Cite this repository button.

License

This project is released under the GNU Affero General Public License v3.0 or later (AGPL-3.0-or-later). See the LICENSE file for the full text.

Authors

See AUTHORS.md.

Contributing

Contributions are welcome! Please:

1. Fork the repository
2. Create a feature branch off main
3. Commit your changes (see Conventional Commits)
4. Open a Pull Request against main

By contributing you agree that your contributions are licensed under the AGPL-3.0-or-later license of this project.

Support

For problems or questions, open an issue in the GitHub repository.