gh-raw-labs-claude-code-marketplace-claude-plugin-plugins-mxcp-plugin/skills/mxcp-expert/assets/project-templates/earthquakes

Earthquakes Example

This example demonstrates how to use MXCP to create a real-time earthquake data API. It shows how to:

• Query live earthquake data from the USGS API
• Transform JSON data using SQL
• Create type-safe endpoints for LLM consumption

Features

• Real-time Data: Fetches the latest earthquake data from USGS
• Type Safety: Strong typing for LLM safety
• SQL Transformations: Complex JSON parsing and data transformation
• Test Coverage: Includes example tests

Getting Started

Prerequisites

Make sure you have MXCP installed:

# Option 1: Install globally
pip install mxcp

# Option 2: Install in development mode (if you cloned the repo)
cd /path/to/mxcp
python -m venv .venv && source .venv/bin/activate
pip install -e .

Running the Example

1. Navigate to the earthquakes example:

   cd examples/earthquakes
   

2. Start the MCP server:

   mxcp serve
   

🔌 Claude Desktop Integration

To use this example with Claude Desktop:

1. Locate Claude's Configuration

Find your Claude Desktop configuration file:

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

2. Configure the MCP Server

Add this configuration to your claude_desktop_config.json:

If you installed MXCP globally:

{
  "mcpServers": {
    "earthquakes": {
      "command": "mxcp",
      "args": ["serve", "--transport", "stdio"],
      "cwd": "/absolute/path/to/mxcp/examples/earthquakes"
    }
  }
}

If you're using a virtual environment:

{
  "mcpServers": {
    "earthquakes": {
      "command": "/bin/bash",
      "args": [
        "-c",
        "cd /absolute/path/to/mxcp/examples/earthquakes && source ../../.venv/bin/activate && mxcp serve --transport stdio"
      ]
    }
  }
}

Important: Replace /absolute/path/to/mxcp with the actual path to your MXCP installation.

3. Restart Claude Desktop

After saving the configuration, restart Claude Desktop to load the new MCP server.

4. Test the Integration

In Claude Desktop, try asking:

• "Show me recent earthquakes above magnitude 5.0"
• "What was the strongest earthquake in the last 24 hours?"
• "List earthquakes near California"

Claude will automatically use the earthquake data tools to answer your questions.

🛠️ Other MCP Clients

This example also works with other MCP-compatible tools:

• mcp-cli: pip install mcp-cli then use the same server config
• Custom integrations: Use the MCP specification to build your own client

Example Usage

Ask your LLM to:

• "Show me recent earthquakes above magnitude 5.0"
• "What was the strongest earthquake in the last 24 hours?"
• "List earthquakes near [location]"

Implementation Details

The example uses:

• DuckDB's read_json_auto function to parse USGS GeoJSON
• SQL window functions for data analysis
• Type-safe parameters for filtering

For more details on:

• Type system: See Type System Documentation
• SQL capabilities: See Integrations Documentation
• Configuration: See Configuration Guide

Project Structure

earthquakes/
├── endpoints/
│   └── tool.yml      # Endpoint definition
├── mxcp-site.yml     # Project configuration
└── tests/            # Example tests

Learn More

• Quickstart Guide - Get started with MXCP
• CLI Reference - Available commands
• Configuration - Project setup