MCP Server¶

The Internet Telemetry MCP (Model Context Protocol) Server enables AI assistants like Claude to directly query outage data, network reachability, and speed test results.

npm: @internet-telemetry/mcp-server

What is MCP?¶

Model Context Protocol (MCP) is an open standard that allows AI assistants to securely connect to external data sources and tools. With the Internet Telemetry MCP server, you can ask Claude questions like:

"Are there any active internet outages in California?"
"What's the reachability status of Google DNS?"
"Show me my recent speed test results"
"Search for incidents affecting Comcast in the last 24 hours"

Installation¶

From npm¶

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

From source¶

git clone https://github.com/internet-telemetry/outage-detection-system.git
cd outage-detection-system/packages/mcp-server
npm install
npm run build

Configuration¶

Claude Desktop¶

Add the server to your Claude Desktop configuration file:

macOSWindows

Edit ~/Library/Application Support/Claude/claude_desktop_config.json:

Edit %APPDATA%\Claude\claude_desktop_config.json:

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

Claude Code (CLI)¶

Add to your project's .mcp.json or global ~/.claude/mcp.json:

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

Or run directly:

npx @internet-telemetry/mcp-server

Available Tools¶

get_incidents¶

Get recent internet outages and incidents from multiple data sources.

Parameters:

Parameter	Type	Description
`hours`	number	Hours of history to fetch (default: 24, max: 168)
`source`	string	Filter by source: `odin`, `radar`, `nws`, `caloes`
`state`	string	Filter by US state code (e.g., `CA`, `TX`)
`min_severity`	number	Minimum severity level (1-5)

Example prompt: "Show me internet outages in California from the last 12 hours"

search_incidents¶

Search incidents by keyword across all fields.

Parameters:

Parameter	Type	Description
`query`	string	Search query (required)
`hours`	number	Hours of history (default: 24)
`limit`	number	Maximum results (default: 50)

Example prompt: "Search for incidents mentioning Comcast or fiber"

get_outages¶

Get unified outage data with ISP attribution.

Parameters:

Parameter	Type	Description
`hours`	number	Hours of history (default: 24)
`isp`	string	Filter by ISP name
`state`	string	Filter by US state code
`active_only`	boolean	Only show ongoing outages

Example prompt: "What active outages are affecting AT&T?"

search_outages¶

Search outages by keyword.

Parameters:

Parameter	Type	Description
`query`	string	Search query (required)
`hours`	number	Hours of history (default: 24)
`limit`	number	Maximum results (default: 50)

Example prompt: "Find outages related to power or weather"

get_reachability¶

Check network reachability for monitored targets.

Parameters:

Parameter	Type	Description
`target`	string	Specific target to check (e.g., `cloudflare-dns`)
`hours`	number	Hours of history (default: 1)

Available targets: cloudflare-dns, google-dns, quad9-dns, opendns, and more.

Example prompt: "Is Cloudflare DNS reachable right now?"

get_speedtest_history¶

Get your speed test history (requires authentication).

Parameters:

Parameter	Type	Description
`limit`	number	Number of results (default: 20, max: 100)

Example prompt: "Show my last 10 speed test results"

get_speedtest_info¶

Get information about the speed test server and your connection.

Example prompt: "What speed test server am I connected to?"

Resources¶

The MCP server also provides these resources:

incident-schema¶

JSON schema for incident objects, useful for understanding the data structure.

URI: ods://schema/incident

data-sources¶

Information about available data sources and their update frequencies.

URI: ods://info/data-sources

Prompts¶

Pre-built prompts for common analysis tasks:

analyze_outage¶

Analyze an outage event in detail.

Arguments:

outage_id (required): The outage ID to analyze

summarize_incidents¶

Generate a summary of recent incidents.

Arguments:

hours (optional): Time period to summarize (default: 24)
state (optional): Focus on specific state

Example Conversations¶

Checking for outages¶

You: Are there any internet outages happening right now in my area?

Claude: Let me check the current outage data for you. [Uses get_incidents tool]

I found 3 active incidents in your region...

Monitoring a specific ISP¶

You: Has Comcast had any issues in the last week?

Claude: I'll search for Comcast-related incidents. [Uses search_incidents tool]

Over the past 7 days, there were 12 reported incidents affecting Comcast...

Speed test analysis¶

You: How has my internet speed been trending?

Claude: Let me pull your speed test history. [Uses get_speedtest_history tool]

Based on your last 20 tests, your average download speed is 450 Mbps...

Troubleshooting¶

Server not connecting¶

Ensure Node.js 18+ is installed
Check that the configuration file path is correct
Restart Claude Desktop/Code after configuration changes

Authentication errors¶

Some endpoints (like speed test history) require authentication. Make sure you're logged into the Internet Telemetry dashboard.

Rate limiting¶

The API has rate limits. If you're seeing errors, wait a few minutes before retrying.

Source Code¶

The MCP server is open source: