npm package: @internet-telemetry/mcp-server
Description: MCP server for Internet Telemetry - query real-time internet outages, network reachability, and speed test data with AI assistants like Claude
Author: Internet Telemetry
Latest version: 1.0.0

# Internet Telemetry MCP Server

[![npm version](https://badge.fury.io/js/@internet-telemetry%2Fmcp-server.svg)](https://www.npmjs.com/package/@internet-telemetry/mcp-server)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)

A [Model Context Protocol (MCP)](https://modelcontextprotocol.io) server that enables AI assistants like Claude to query real-time internet outage data, network reachability, and speed test results.

## Features

- **Real-time Outage Data**: Query internet outages from multiple sources (ODIN, Cloudflare Radar, NWS, Cal OES)
- **Network Reachability**: Check the status of major DNS providers and network endpoints
- **Speed Test History**: Access your speed test results and trends
- **Natural Language Queries**: Ask Claude about outages in plain English

## Installation

```bash
npm install -g @internet-telemetry/mcp-server
```

## Quick Start

### Claude Desktop

Add to your Claude Desktop config (`~/Library/Application Support/Claude/claude_desktop_config.json` on macOS):

```json
{
  "mcpServers": {
    "internet-telemetry": {
      "command": "npx",
      "args": ["-y", "@internet-telemetry/mcp-server"]
    }
  }
}
```

### Claude Code

Add to `.mcp.json` in your project or `~/.claude/mcp.json` globally:

```json
{
  "mcpServers": {
    "internet-telemetry": {
      "command": "npx",
      "args": ["-y", "@internet-telemetry/mcp-server"]
    }
  }
}
```

## Available Tools

| Tool | Description |
|------|-------------|
| `get_incidents` | Get recent internet outages and incidents |
| `search_incidents` | Search incidents by keyword |
| `get_outages` | Get unified outage data with ISP attribution |
| `search_outages` | Search outages by keyword |
| `get_reachability` | Check network reachability for monitored targets |
| `get_speedtest_history` | Get your speed test history |
| `get_speedtest_info` | Get speed test server and connection info |

## Example Usage

Once configured, you can ask Claude:

- "Are there any internet outages in California right now?"
- "What's the reachability status of Google DNS?"
- "Show me incidents affecting Comcast in the last 24 hours"
- "How has my internet speed been trending this week?"

## Tool Details

### get_incidents

```
Parameters:
  - hours: number (default: 24, max: 168)
  - source: "odin" | "radar" | "nws" | "caloes"
  - state: US state code (e.g., "CA")
  - min_severity: 1-5
```

### search_incidents

```
Parameters:
  - query: string (required)
  - hours: number (default: 24)
  - limit: number (default: 50)
```

### get_outages

```
Parameters:
  - hours: number (default: 24)
  - isp: ISP name filter
  - state: US state code
  - active_only: boolean
```

### get_reachability

```
Parameters:
  - target: string (e.g., "cloudflare-dns", "google-dns")
  - hours: number (default: 1)
```

### get_speedtest_history

```
Parameters:
  - limit: number (default: 20, max: 100)
```

## Resources

The server also provides MCP resources:

- `ods://schema/incident` - JSON schema for incident objects
- `ods://info/data-sources` - Available data sources and update frequencies

## Prompts

Pre-built prompts for common tasks:

- `analyze_outage` - Detailed analysis of a specific outage
- `summarize_incidents` - Summary of recent incidents

## Development

```bash
# Clone the repository
git clone https://github.com/internet-telemetry/outage-detection-system.git
cd outage-detection-system/packages/mcp-server

# Install dependencies
npm install

# Build
npm run build

# Run in development mode
npm run dev
```

## API

This MCP server connects to the Internet Telemetry API at `https://ods-api.m-8b1.workers.dev`. For direct API access, see the [API documentation](https://ods-docs.pages.dev).

## Requirements

- Node.js 18+
- A compatible MCP client (Claude Desktop, Claude Code, or other MCP-enabled applications)

## License

MIT

## Links

- [Documentation](https://ods-docs.pages.dev/guides/mcp-server/)
- [API Reference](https://ods-docs.pages.dev/api/overview/)
- [GitHub Repository](https://github.com/internet-telemetry/outage-detection-system)
- [Internet Telemetry Dashboard](https://internet-telemetry.com)