# Connectivity Diagnostics MCP Server

An MCP server that gives your AI assistant real network diagnostic
capabilities. Instead of guessing about your network,
the AI can actually run tools like ping, traceroute, DNS lookups, and
TLS certificate checks — right on your machine — and interpret the
results for you.

Works on Windows, macOS, and Linux.

**Important:** This server is designed to run locally on your machine.
The diagnostic tools (ping, traceroute, etc.) execute against your
local network stack — that's the whole point. If you ran the server on
a remote host, the tools would diagnose *that* host's network, not
yours. For this reason, you need an MCP client that supports **local
stdio** servers (see compatibility notes below).

---

## Try These First

Once installed, try asking your AI assistant questions like these:

- *"How is my connection to google.com? Run every diagnostic you have."*
- *"Why might my connection to AWS us-east-1 be slow? Investigate."*
- *"Check the SSL certificate on mydomain.com — is it about to expire?"*
- *"Run a full self-diagnostic of my network configuration."*
- *"What DNS server am I using, and is it resolving correctly?"*
- *"Trace the route to cloudflare.com and identify any high-latency hops."*
- *"Break down the HTTP timing for api.example.com — where is the delay?"*
- *"What devices are on my local network right now?"*

---

## Available Tools

| Tool             | What It Does                                                  |
|------------------|---------------------------------------------------------------|
| `ping`           | ICMP ping — latency and packet loss to any host               |
| `curl`           | HTTP headers — check reachability and status codes            |
| `tracert`        | Route tracing — hop-by-hop path to a host                     |
| `nslookup`       | DNS lookup — verify domain name resolution                    |
| `ipconfig`       | Local adapter config — IPs, gateway, DNS servers              |
| `routing_table`  | System routing table — how packets are directed               |
| `http_timing`    | Detailed HTTP timing: DNS, TCP, TLS, TTFB breakdown           |
| `ssl_check`      | TLS certificate details and validity                          |
| `arp_table`      | LAN device discovery via ARP cache                            |
| `mtr`            | Combined ping + traceroute with per-hop loss stats            |

---

## Prerequisites

Install the MCP Python package:

```bash
pip install "mcp[cli]"
```

Download `connectivity_mcp_server.py` and note its full path. You will
need it in the configuration steps below.

---

## Setup: Claude Desktop

Claude Desktop connects to local MCP servers via stdio. You add the
server to a JSON config file and restart the app.

### 1. Find the config file

| OS      | Path                                                            |
|---------|-----------------------------------------------------------------|
| Windows | `%APPDATA%\Claude\claude_desktop_config.json`                   |
| macOS   | `~/Library/Application Support/Claude/claude_desktop_config.json` |

Paste the path into Explorer or Finder to open the folder. If the file
does not exist, create it.

### 2. Add the server

Open `claude_desktop_config.json` and add or merge the following. Replace
the path with the actual location of `connectivity_mcp_server.py` on
your machine:

**Windows:**
```json
{
  "mcpServers": {
    "connectivity-diagnostics": {
      "command": "python",
      "args": [
        "C:\\path\\to\\connectivity_mcp_server.py"
      ]
    }
  }
}
```

**macOS / Linux:**
```json
{
  "mcpServers": {
    "connectivity-diagnostics": {
      "command": "python3",
      "args": [
        "/path/to/connectivity_mcp_server.py"
      ]
    }
  }
}
```

> If you already have other MCP servers configured, add the
> `"connectivity-diagnostics"` block inside the existing `"mcpServers"`
> object — don't replace the whole file.

### 3. Restart Claude Desktop

Fully quit and relaunch the app. The MCP server starts automatically
when Claude needs it.

### 4. Verify

Ask Claude: *"What network diagnostic tools do you have available?"*

---

## Setup: Cursor

Cursor supports local MCP servers through a `mcp.json` config file.

### 1. Create the config file

You can configure MCP servers globally or per-project:

| Scope      | Path                           |
|------------|--------------------------------|
| Global     | `~/.cursor/mcp.json`           |
| Project    | `.cursor/mcp.json` (in project root) |

### 2. Add the server

Create or edit the `mcp.json` file. Replace the path with the actual
location of `connectivity_mcp_server.py` on your machine:

**Windows:**
```json
{
  "mcpServers": {
    "connectivity-diagnostics": {
      "command": "python",
      "args": [
        "C:\\path\\to\\connectivity_mcp_server.py"
      ]
    }
  }
}
```

**macOS / Linux:**
```json
{
  "mcpServers": {
    "connectivity-diagnostics": {
      "command": "python3",
      "args": [
        "/path/to/connectivity_mcp_server.py"
      ]
    }
  }
}
```

### 3. Restart Cursor

Relaunch the editor or reload the window. You can verify the server is
connected under **Settings > Tools & Integrations > MCP Tools**.

---

## What About ChatGPT?

ChatGPT's MCP support (Developer Mode) only connects to **remote**
servers over HTTPS — it does not support local stdio. Since this server
is designed to diagnose *your* machine's network, running it remotely
would defeat the purpose. ChatGPT is not compatible with this server
at this time.

---

## Troubleshooting

**The AI doesn't see the tools after restart:**
- Double-check the file path in your config — use `\\` on Windows.
- Confirm `python` (or `python3`) is on your system PATH:
  run `python --version` in a terminal.
- Check the client's MCP logs if available.

**`tracert` or `mtr` times out:**
- This is normal for hosts that block ICMP. The timeouts are generous
  (45s for tracert, 60s for mtr).
- Try a well-known host like `8.8.8.8` to confirm the tool works.

**`mtr` command not found:**
- Windows: Install [WinMTR](https://github.com/White-Tiger/WinMTR) and
  ensure it is on your PATH.
- macOS: `brew install mtr`
- Linux: `sudo apt install mtr` (Debian/Ubuntu) or
  `sudo dnf install mtr` (Fedora/RHEL)