hosting-doctor-mcp

An MCP server that diagnoses web hosting and server problems by combining live diagnostic checks (HTTP, SSL, DNS, security headers) with a RAG-searchable knowledge base of troubleshooting notes, stored in Weaviate.

Point Claude, Cursor, or any other MCP client at a URL and a symptom ("visitors see a blank white page", "certificate warning in the browser", "site went down after I changed nameservers") and it gets back live evidence plus the most relevant troubleshooting notes — then reasons over both to explain what's actually wrong, instead of guessing from the symptom text alone.

Why this exists

Most "AI + hosting" tools fall into one of two buckets: an official API wrapper (DigitalOcean, WordPress, and Weaviate all already ship their own MCP servers for CRUD-style operations against their own platforms), or a generic Lighthouse/PageSpeed wrapper (several of these already exist too). Neither actually diagnoses anything — they just expose an API.

hosting-doctor-mcp is a synthesis tool instead: it runs the live checks and retrieves the relevant troubleshooting context in one call, then leaves the actual reasoning to the calling agent, which has the full conversation and can explain the result in plain language. That retrieval-not-generation split is deliberate — the tool's job is to gather evidence, not to write the final answer.

Related MCP server: webcheck-mcp

Tools

The knowledge base (kb/*.md) currently covers 17 issues: 502/504 gateway errors, mixed content warnings, WordPress white screen of death, DNS propagation delays, SSL chain issues, CORS errors, high TTFB, redirect loops, CDN cache staleness, PHP memory limit errors, 429 rate limiting, Let's Encrypt renewal failures, generic 500 errors, email deliverability (SPF/DKIM/DMARC), disk space exhaustion, connection-refused/port issues, and database connection pool exhaustion. Each note is frontmatter (title, tags, symptoms) plus a short cause-and-fix body — see kb/ to read or extend them.

Architecture

MCP client (Claude Desktop / Cursor / Claude Code)
        │  stdio (JSON-RPC)
        ▼
hosting-doctor-mcp server (Node + TypeScript, @modelcontextprotocol/sdk)
    ├── check_http_status / check_ssl / check_dns / check_security_headers
    │     → Node built-ins only (fetch, tls, dns/promises) — zero external deps
    │
    └── search_troubleshooting_kb / diagnose
          → Weaviate Cloud (hybrid search, text2vec-weaviate hosted embeddings)

The four live-check tools have no external dependencies and work immediately. The KB search depends on a Weaviate Cloud sandbox — see setup below.

Setup

1. Install and build

git clone https://github.com/huzaifashuja/hosting-doctor-mcp.git
cd hosting-doctor-mcp
npm install
npm run build

2. (Optional but recommended) Set up the knowledge base

The KB search and diagnose tools need a Weaviate Cloud sandbox (free tier is enough):

1. Create a free sandbox cluster at console.weaviate.cloud.

2. Copy .env.example to .env and fill in WEAVIATE_URL and WEAVIATE_API_KEY from the sandbox's dashboard.

3. Ingest the knowledge base:

   npm run ingest

Without this step, the four live-check tools still work fine — search_troubleshooting_kb and diagnose will just report the KB as unavailable.

3. Connect it to an MCP client

Claude Desktop — add to claude_desktop_config.json:

{
  "mcpServers": {
    "hosting-doctor": {
      "command": "node",
      "args": ["/absolute/path/to/hosting-doctor-mcp/dist/src/index.js"],
      "env": {
        "WEAVIATE_URL": "https://your-cluster-id.weaviate.network",
        "WEAVIATE_API_KEY": "your-weaviate-api-key"
      }
    }
  }
}

Cursor — add the same shape to .cursor/mcp.json in your project (or the global Cursor MCP config).

Claude Code — claude mcp add hosting-doctor -- node /absolute/path/to/hosting-doctor-mcp/dist/src/index.js

4. Try it

Ask your MCP client something like:

My site example.com is showing a certificate warning, can you check what's wrong?

or

Diagnose why mysite.com is showing a blank white screen.

Development

npm run dev       # run the server directly with tsx (no build step)
npm run inspect   # build, then open the MCP Inspector for manual tool testing
npm run ingest    # re-ingest kb/*.md into Weaviate (safe to re-run)

Project structure

src/
  index.ts                 # MCP server entrypoint, tool registration
  tools/
    checkHttpStatus.ts
    checkSsl.ts
    checkDns.ts
    checkSecurityHeaders.ts
    searchKb.ts
    diagnose.ts
  lib/
    weaviateClient.ts       # Weaviate connection + collection schema
  types.ts
kb/
  *.md                      # curated troubleshooting notes
scripts/
  ingest.ts                 # chunks + upserts kb/*.md into Weaviate

License

MIT