eladmasa/earthquake-mcp-server

🌍 Earthquake MCP Server

Model Context Protocol (MCP) server providing real-time earthquake data from the USGS Earthquake Hazards Program.

Features

• Real-time earthquake data from USGS API
• Flexible filtering by magnitude, time range, and location
• Detailed earthquake information including depth, significance, and alert levels
• Statistical analysis with magnitude distribution and depth statistics
• No API key required - Uses public USGS API

Available Tools

1. get_recent_earthquakes

Fetch recent earthquakes with optional filters.

Parameters:

• min_magnitude (optional): Minimum earthquake magnitude (e.g., 2.5, 4.0)
• days (optional): Number of days to look back (default: 7)
• limit (optional): Maximum number of results (default: 100)

2. get_significant_earthquakes

Get significant earthquakes (magnitude 4.5+) from recent days.

Parameters:

• days (optional): Number of days to look back (default: 7)
• min_magnitude (optional): Minimum magnitude threshold (default: 4.5)

3. get_earthquake_details

Get detailed information about a specific earthquake by its USGS event ID.

Parameters:

• event_id (required): USGS event ID (e.g., "us6000jllz")

4. get_earthquake_statistics

Get statistical summary including count, average magnitude, and distribution.

Parameters:

• min_magnitude (optional): Minimum magnitude to include
• days (optional): Number of days to analyze (default: 7)

Installation

Prerequisites

• Python 3.11 or higher
• pip package manager

Setup

1. Clone the repository:

git clone <your-repo-url>
cd earthquake-mcp-server

2. Create and activate a virtual environment:

python -m venv venv
source venv/bin/activate  # On Windows: venv\Scripts\activate

3. Install dependencies:

pip install -r requirements.txt

Usage

Running Standalone

Start the MCP server:

python -m server.main

The server will start and listen for MCP protocol messages via stdio.

Using with Claude Desktop

Add this configuration to your Claude Desktop config file:

macOS: ~/Library/Application Support/Claude/claude_desktop_config.json Windows: %APPDATA%/Claude/claude_desktop_config.json

{
  "mcpServers": {
    "earthquake": {
      "command": "python",
      "args": [
        "-m",
        "server.main"
      ],
      "cwd": "/absolute/path/to/earthquake-mcp-server",
      "env": {
        "PYTHONPATH": "/absolute/path/to/earthquake-mcp-server"
      }
    }
  }
}

Replace /absolute/path/to/earthquake-mcp-server with the actual path to your project.

Restart Claude Desktop, and the earthquake tools will be available!

Example Queries

Once connected to Claude Desktop, you can ask:

• "Show me recent earthquakes above magnitude 4.0"
• "What significant earthquakes happened in the past 24 hours?"
• "Get statistics for earthquakes in the last 30 days"
• "Show me details for earthquake us6000jllz"
• "Are there any earthquakes with tsunami warnings?"

Project Structure

earthquake-mcp-server/
├── server/
│   ├── __init__.py
│   ├── main.py          # MCP server entry point
│   └── tools.py         # MCP tool implementations
├── services/
│   ├── __init__.py
│   └── usgs_client.py   # USGS API client
├── models/
│   ├── __init__.py
│   └── earthquake.py    # Pydantic data models
├── utils/
│   └── __init__.py
├── tests/
│   └── __init__.py
├── requirements.txt     # Python dependencies
├── pyproject.toml       # Project metadata
└── README.md           # This file

Data Source

This server uses the USGS Earthquake Hazards Program API:

• Real-time earthquake data worldwide
• Updated continuously
• No authentication required
• Free to use

Development

Running Tests

pytest tests/

Code Style

This project follows:

• PEP 8 coding standards
• Type hints throughout
• reStructuredText docstring format

License

MIT License - feel free to use and modify as needed.

Contributing

Contributions welcome! Please ensure:

• Code follows PEP 8
• All functions have type hints and docstrings
• Tests pass before submitting PRs

Acknowledgments

• USGS Earthquake Hazards Program for providing free, real-time earthquake data
• Anthropic for the Model Context Protocol specification