network_outage_mcp

flinntech/network_outage_mcp

3.2

If you are the rightful owner of network_outage_mcp and would like to certify it and/or have it hosted online, please leave a comment on the right or send an email to dayong@mcphub.com.

MCP Server for checking internet outages and issues using the IODA (Internet Outage Detection and Analysis) API from Georgia Tech.

Tools
5
Resources
0
Prompts
0

Network Outage MCP Server

MCP Server for checking internet outages and issues using the IODA (Internet Outage Detection and Analysis) API from Georgia Tech.

Overview

This MCP server provides tools to monitor and analyze internet outages worldwide using real-time data from the IODA project. IODA monitors the Internet in near-realtime to identify macroscopic Internet outages affecting network operators (ASNs) and countries.

Features

  • Real-time Outage Detection: Monitor internet connectivity issues as they happen
  • Multiple Data Sources: Leverages BGP, active probing (ping), and other data sources
  • Global Coverage: Monitor outages by country or Autonomous System Number (ASN)
  • Event Tracking: Get detailed information about current and past outage events
  • Alert System: Receive alerts when anomalies are detected

Available Tools

1. get_outage_signals

Get internet outage signal data for a specific country or ASN over a time period.

Parameters:

  • entityType: Type of entity (country, asn, or region)
  • entityCode: Entity identifier (e.g., US for United States, 174 for ASN 174)
  • from: Start time as Unix timestamp
  • until: End time as Unix timestamp
  • datasource (optional): Specific data source (bgp, ping-slash24, merit-nt)

Example:

{
  "entityType": "country",
  "entityCode": "US",
  "from": 1609459200,
  "until": 1609545600
}

2. get_active_events

Get currently active or recent internet outage events.

Parameters:

  • from (optional): Start time as Unix timestamp
  • until (optional): End time as Unix timestamp
  • entityType (optional): Filter by entity type (country or asn)
  • entityCode (optional): Filter by specific entity code
  • limit (optional): Maximum number of events to return (default: 100)

3. get_outage_alerts

Get real-time alerts about potential internet outages.

Parameters:

  • entityType: Type of entity (country or asn)
  • entityCode (optional): Specific entity code (omit to get all alerts)
  • from (optional): Start time as Unix timestamp
  • until (optional): End time as Unix timestamp

4. search_entity

Search for countries or ASNs by name or code.

Parameters:

  • entityType: Type of entity to search (country or asn)
  • query: Search query (country name, code, or ASN number)

5. get_datasources

Get information about available data sources used by IODA.

Parameters: None

Transport Options

This MCP server supports two transport modes:

  1. stdio (Standard Input/Output) - For local integration with Claude Desktop
  2. StreamableHTTP - For remote access by AI agents over HTTP (MCP standard transport)

Installation & Usage

StreamableHTTP Server (For AI Agents)

The StreamableHTTP server provides the standard MCP HTTP transport that allows AI agents to access the MCP server remotely. This implements the official MCP Streamable HTTP specification.

Prerequisites
  • Node.js 20 or higher
  • npm or yarn
Install Dependencies
npm install
Build
npm run build
Run StreamableHTTP Server
npm run start:http

By default, the server runs on http://0.0.0.0:3001. You can customize this with environment variables:

PORT=8080 HOST=localhost npm run start:http
HTTP Endpoints
  • MCP Endpoint: POST /mcp - Send JSON-RPC messages (initialize, call tools, etc.)
  • MCP Stream: GET /mcp - Establish SSE stream for ongoing communication (requires session ID)
  • Session Termination: DELETE /mcp - Terminate an active session
  • Health Check: GET /health - Check server status
How It Works
  1. Initialize: Client sends an initialize request to POST /mcp
  2. Session Created: Server responds with a session ID in the Mcp-Session-Id header
  3. Subsequent Requests: Client includes the session ID in headers for all future requests
  4. Streaming: Client can open a GET connection to receive server-initiated messages
Example: Connecting from an AI Agent
// Step 1: Initialize the session
const initResponse = await fetch('http://localhost:3001/mcp', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    jsonrpc: '2.0',
    id: 1,
    method: 'initialize',
    params: {
      protocolVersion: '2024-11-05',
      capabilities: {},
      clientInfo: {
        name: 'my-client',
        version: '1.0.0',
      },
    },
  }),
});

const sessionId = initResponse.headers.get('Mcp-Session-Id');

// Step 2: Call a tool with the session ID
const toolResponse = await fetch('http://localhost:3001/mcp', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
    'Mcp-Session-Id': sessionId,
  },
  body: JSON.stringify({
    jsonrpc: '2.0',
    id: 2,
    method: 'tools/call',
    params: {
      name: 'get_active_events',
      arguments: {},
    },
  }),
});

Docker

The Docker container runs the HTTP server by default, exposing the StreamableHTTP transport on port 3001.

Build the Docker Image
docker build -t network-outage-mcp .
Run with Docker Compose
docker-compose up -d

The server will be available at http://localhost:3001/mcp

Run with Docker
docker run -d -p 3001:3001 --name network-outage-mcp network-outage-mcp

Access the server at http://localhost:3001/mcp

Stdio Server (For Claude Desktop)

The stdio server is used for local integration with Claude Desktop.

Prerequisites
  • Node.js 20 or higher
  • npm or yarn
Install Dependencies
npm install
Build
npm run build
Run
npm start

Configuration with Claude Desktop

Add this server to your Claude Desktop configuration file:

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

Windows: %APPDATA%\Claude\claude_desktop_config.json

Using Docker:
{
  "mcpServers": {
    "network-outage": {
      "command": "docker",
      "args": ["run", "-i", "network-outage-mcp"]
    }
  }
}
Using Node directly:
{
  "mcpServers": {
    "network-outage": {
      "command": "node",
      "args": ["/path/to/network_outage_mcp/build/index.js"]
    }
  }
}

Example Queries

Once configured, you can ask Claude questions like:

  • "Check for internet outages in the United States in the last 24 hours"
  • "Show me active outage events globally"
  • "Get signal data for ASN 174 from yesterday"
  • "Are there any alerts for internet connectivity issues in France?"
  • "What data sources does IODA use for monitoring?"

Understanding Unix Timestamps

The IODA API uses Unix timestamps (seconds since January 1, 1970). Here are some helpful conversions:

  • Last 24 hours: Date.now()/1000 - 86400 to Date.now()/1000
  • Last week: Date.now()/1000 - 604800 to Date.now()/1000
  • Specific date: Use online converters or JavaScript's new Date('2024-01-01').getTime()/1000

Data Sources

IODA uses multiple data sources to detect outages:

  • BGP: Border Gateway Protocol routing data
  • Active Probing: Ping measurements to /24 networks
  • Darknet: Analysis of unsolicited traffic
  • Merit-NT: Network telescope data

API Reference

This server uses the IODA v2 API: https://api.ioda.inetintel.cc.gatech.edu/v2/

For more information about IODA:

Troubleshooting

Connection Issues

If you encounter connection problems:

  1. Verify internet connectivity
  2. Check if the IODA API is accessible: curl https://api.ioda.inetintel.cc.gatech.edu/v2/
  3. Review Docker logs: docker logs network-outage-mcp

Invalid Entity Codes

If you get errors about invalid entity codes:

  • Use ISO 3166-1 alpha-2 country codes (e.g., US, GB, FR)
  • For ASNs, use the numeric value without "AS" prefix (e.g., 174, not AS174)
  • Use the search_entity tool to find the correct codes

Development

Project Structure

network_outage_mcp/
├── src/
│   └── index.ts          # Main server implementation
├── build/                # Compiled JavaScript (generated)
├── Dockerfile            # Docker configuration
├── docker-compose.yml    # Docker Compose configuration
├── package.json          # Node.js dependencies
├── tsconfig.json         # TypeScript configuration
└── README.md            # This file

Making Changes

  1. Edit source files in src/
  2. Rebuild: npm run build
  3. Test locally: npm start
  4. Rebuild Docker image: docker build -t network-outage-mcp .

License

MIT

Credits

This server uses data from the IODA (Internet Outage Detection and Analysis) project at Georgia Tech's Internet Intelligence Research Lab.

For questions about IODA data or API access, contact: ioda-info@cc.gatech.edu