Web Check MCP

Agent wrapper for Lissy93/web-check — 31 OSINT checks as MCP tools + CLI.

Gap verified 2026-07-25: no public MCP/SDK/Hermes skill existed for this API. This package fills it.

Features

• 8 MCP tools: webcheck_run, webcheck_ssl, webcheck_dns, webcheck_security, webcheck_headers, webcheck_whois, webcheck_list_checks, webcheck_health
• 31 OpenAPI checks from upstream (ssl, dns, headers, ports, firewall, whois, …)
• Presets: quick | security | server | quality | heavy | all
• Parallel fan-out + payload truncation (agent-context safe)
• Zero pip deps — Python 3.10+ stdlib only
• STDIO JSON-RPC with initialize handshake + tool annotations (readOnlyHint + openWorldHint)

Public API works (with fallback)

Two public bases are tried automatically:

Set WEB_CHECK_BASE_URL explicitly to skip probing. Fallback auto-enables when base starts with https://web-check. and can be forced via WebCheckClient(fallback=True).

No key, no auth.

Self-host (optional)

For heavy load or offline use:

docker run -d --name web-check -p 3000:3000 lissy93/web-check
export WEB_CHECK_BASE_URL=http://127.0.0.1:3000/api

Or compose (upstream + thin MCP image):

docker compose up -d web-check
# MCP stdio still launched by host; see Dockerfile ENTRYPOINT

Upstream Go rewrite xray-web/web-check-api is early WIP — prefer Node/Docker image for full endpoint parity.

Quick Start

# from repo root
pip install -e .
# or: python3 -m pip install web-check-mcp

# Manifest
python3 -m src.server --manifest

# List checks
python3 -m src.server list --group quick

# Health probe
python3 -m src.server health

# Run quick recon (needs live API)
python3 -m src.server run example.com --group quick

# Single check
python3 -m src.server check ssl example.com

# MCP STDIO (Claude Desktop / Hermes / Cursor)
python3 -m src.server --stdio

Library

from src.client import WebCheckClient

client = WebCheckClient(base_url="http://127.0.0.1:3000/api")
print(client.run("example.com", group="quick"))
print(client.check_one("ssl", "example.com"))

MCP client config

{
  "mcpServers": {
    "web-check": {
      "command": "python3",
      "args": ["-m", "src.server", "--stdio"],
      "cwd": "/absolute/path/to/web-check-mcp",
      "env": {
        "WEB_CHECK_BASE_URL": "http://127.0.0.1:3000/api"
      }
    }
  }
}

After pip install web-check-mcp:

{
  "mcpServers": {
    "web-check": {
      "command": "web-check-mcp",
      "args": ["--stdio"],
      "env": {
        "WEB_CHECK_BASE_URL": "https://web-check.as93.net/api"
      }
    }
  }
}

Official registry metadata lives in server.json (io.github.AMEOBIUS-space/web-check-mcp). Publish with mcp-publisher after the next PyPI release that includes the mcp-name marker above.

Tool Reference

Env: WEB_CHECK_BASE_URL, WEB_CHECK_TIMEOUT, WEB_CHECK_MAX_WORKERS, WEB_CHECK_MAX_CHARS.

Tests

python3 -m pytest tests/ -v

All network paths mocked — no live API required for CI.

License

MIT. Upstream Web Check © Alicia Sykes, MIT.

Not affiliated with Lissy93; thin agent-facing client only.