# fleetcheck-mcp

[![CI](https://github.com/seifosmaan53/fleetcheck-mcp/actions/workflows/ci.yml/badge.svg)](https://github.com/seifosmaan53/fleetcheck-mcp/actions/workflows/ci.yml)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE)
[![Python 3.10+](https://img.shields.io/badge/python-3.10%2B-blue.svg)](https://www.python.org/downloads/)

**An MCP server that gives Claude safe, read-only network & service diagnostics — ping, DNS, HTTP health, TLS expiry, single-port checks, traceroute, and whole-fleet sweeps.**

## Why this exists

My day job is keeping 890 retail stores' registers and networks online. When a store calls saying "the internet is down", there's a first-call ritual every ops person knows: ping the gateway, check DNS, hit the health endpoint, see if the VPN port answers, glance at the cert that's been quietly counting down to expiry. fleetcheck packages exactly those checks as MCP tools, so Claude can run the ritual for you — across one host or fifty — and tell you what's actually broken.

## Tools

| Tool | What it answers | Example question to ask Claude |
|---|---|---|
| `ping_host` | Is this machine reachable, and how lossy/slow is the path? | "Ping 10.1.42.1 and tell me the packet loss." |
| `dns_lookup` | Does this name resolve, to what, and how fast? (A/AAAA/CNAME/MX/TXT/NS) | "What do the MX records for example.com look like?" |
| `http_health` | Is this web endpoint up, how fast, and where do redirects land? | "Check https://portal.example.com/health and show the redirect chain." |
| `tcp_port_check` | Is the service listening on this one port? | "Is port 443 open on the store-042 gateway?" |
| `tls_cert_check` | Who issued this cert, which names does it cover, and when does it expire? | "Is the cert on vpn.example.com expiring soon?" |
| `traceroute_host` | Where along the path does traffic slow down or die? | "Traceroute to 8.8.8.8 and find the slow hop." |
| `fleet_sweep` | Which of my hosts are down right now, and which is slowest? | "Sweep these 5 store gateways and tell me which are down." |

Every tool returns a structured dict. Failures — host down, DNS miss, timeout, bad input — come back as data (`{"ok": false, "error": "..."}`), never as a crashed tool call, so Claude can reason about *why* something failed.

## Install

Requires Python 3.10+ and [uv](https://docs.astral.sh/uv/) (for `uvx`), or plain pip.

> **Installs from this repo for now.** A PyPI release is set up (trusted publishing,
> see `.github/workflows/publish.yml`) but hasn't been cut yet, so `uvx fleetcheck-mcp`
> and `pip install fleetcheck-mcp` won't resolve. Use the Git commands below — they
> install the same package.

### Claude Code

```bash
claude mcp add fleetcheck -- uvx --from git+https://github.com/seifosmaan53/fleetcheck-mcp fleetcheck-mcp
```

### Claude Desktop

Add to your `claude_desktop_config.json`:

```json
{
  "mcpServers": {
    "fleetcheck": {
      "command": "uvx",
      "args": [
        "--from",
        "git+https://github.com/seifosmaan53/fleetcheck-mcp",
        "fleetcheck-mcp"
      ]
    }
  }
}
```

### With pip

```bash
pip install git+https://github.com/seifosmaan53/fleetcheck-mcp
fleetcheck-mcp   # runs the server over stdio
```

## Example conversation

> **You:** Claude, sweep these 5 store gateways and tell me which are down: 10.1.1.1, 10.1.2.1, 10.1.3.1, 10.1.4.1, 10.1.5.1
>
> **Claude:** *(calls `fleet_sweep` with `check="ping"`)*
> 4 of 5 gateways are up. **10.1.3.1 is down** — 100% packet loss. Of the reachable ones, 10.1.5.1 is the slowest at 240 ms average RTT; the rest answer in under 20 ms. Want me to traceroute 10.1.3.1 to see where the path dies?

Other things that work well:

- "Ping the store-042 gateway, and if it's up, check whether port 443 answers."
- "Check every cert on this list and flag anything expiring inside 30 days."
- "portal.example.com feels slow — check DNS resolution time, then HTTP latency, and tell me which one is the problem."

## Safety

fleetcheck is a **diagnostics tool, not a scanner**, and it's built to stay that way:

- **Read-only.** Every tool observes (ICMP echo, DNS query, HTTP GET, TCP connect, TLS handshake, traceroute). Nothing configures, writes to, or restarts anything.
- **Single-port checks only.** `tcp_port_check` (and `fleet_sweep` with `check="port"`) accepts exactly one integer port per call. Port ranges and lists are rejected by validation.
- **50-host cap.** `fleet_sweep` refuses lists longer than 50 hosts, and runs at most 10 checks concurrently.
- **Strict input validation.** Hosts are whitelist-validated (hostname characters or parseable IPs); shell metacharacters and flag-like leading dashes are rejected. Subprocess arguments are always passed as lists — never through a shell. Every numeric input is clamped and every call has a timeout.
- **Use it on your own infrastructure.** These checks are harmless individually, but you should only point them at systems you operate or have explicit permission to test.

## Development

```bash
git clone https://github.com/seifosmaan53/fleetcheck-mcp
cd fleetcheck-mcp
python -m venv .venv && source .venv/bin/activate
pip install -e ".[dev]"
pytest
```

Tests run entirely against localhost and canned command output (macOS **and** Linux ping formats) — no external network required. CI runs the suite on Python 3.10–3.12; releases publish to PyPI via trusted publishing.

## License

[MIT](LICENSE) — © 2026 [Seif Osman](https://seifosman.com)