UptimeCheck MCP Server

A Model Context Protocol (MCP) server that provides network uptime checking tools. Fully compatible with:

• ✅ N8N (MCP Client Tool v1.2+)
• ✅ Open WebUI (direct API integration)
• ✅ Claude Desktop (stdio transport)
• ✅ Any MCP-compliant client

The server supports multiple MCP protocol versions and runs as both an MCP server and a standalone web API.

🚀 Quick Start

N8N Integration

MCP Client Tool Settings:
  Endpoint: http://mcp-checkuptime.mcp.svc.cluster.local:8080  # Internal K8s
  # OR: https://your-domain.com  # External
  Server Transport: HTTP Streamable
  Authentication: None
  Tools to Include: All

See N8N Setup Guide for complete instructions.

Docker Deployment

docker-compose up -d

📚 Documentation

Comprehensive documentation is available in the ai-docs/ folder:

• N8N Setup Guide - Complete N8N + Kubernetes setup
• Authentication Guide - Bearer token configuration
• Kubernetes Guide - Traefik + ingress setup
• Troubleshooting - Connection issues
• Full Documentation Index - All documentation

Table of Contents

• Prerequisites Installation
  • 1. Install Docker Desktop
    • Windows
    • macOS
    • Linux
  • 2. Install Docker MCP Plugin
  • 3. Install Claude Desktop
    • Windows
    • macOS
• MCP Server Setup
  • 1. Clone and Build
  • 2. Configure Claude Desktop
  • 3. Test the Server
• Web Server Mode
  • Running as Web API
  • API Endpoints
  • Testing the Web API
• Open WebUI Integration
  • Install Open WebUI
  • Configure MCP Server
  • Add to Open WebUI
• Available Tools
  • ping_host
  • check_website
• Usage Examples
• Troubleshooting
• Development
• Contributing
• License
• Acknowledgements

Prerequisites Installation

1. Install Docker Desktop

Windows

• Download Docker Desktop from docker.com/products/docker-desktop
• Run the installer and follow setup wizard
• Enable WSL 2 integration if prompted
• Restart your computer after installation

macOS

• Download Docker Desktop for Mac from the official site
• Drag Docker.app to Applications folder
• Launch Docker Desktop and complete setup

Linux

# Ubuntu/Debian
curl -fsSL https://get.docker.com -o get-docker.sh
sudo sh get-docker.sh
sudo usermod -aG docker $USER
# Log out and back in

2. Install Docker MCP Plugin

# Install the Docker MCP plugin
docker plugin install docker/mcp-plugin:latest

# Verify installation
docker mcp version

3. Install Claude Desktop

Windows

• Download from claude.ai/download
• Run installer and complete setup

macOS

• Download Claude Desktop for macOS
• Move to Applications folder
• Launch and sign in

MCP Server Setup

1. Clone and Build

# Clone this repository
git clone <your-repo-url>
cd uptimecheck-mcp-server

# Build the Docker image
docker build -t uptimecheck-mcp-server .

2. Set Up MCP Configuration Files

Create Directory Structure

Windows

# Create MCP directories
mkdir $env:USERPROFILE\.docker\mcp\catalogs -Force

macOS/Linux:

# Create MCP directories
mkdir -p ~/.docker/mcp/catalogs

Create custom.yaml

File Location:

• Windows: %USERPROFILE%.docker\mcp\catalogs\custom.yaml
• macOS: ~/.docker/mcp/catalogs/custom.yaml
• Linux: ~/.docker/mcp/catalogs/custom.yaml

Content:

version: 2
name: custom
displayName: Custom MCP Servers
registry:
  uptimecheck:
    description: "Checks server and website uptime (ping, curl)"
    title: "UptimeCheck"
    type: server
    dateAdded: "2025-09-15T13:31:00Z"
    image: uptimecheck-mcp-server:latest
    ref: ""
    readme: ""
    toolsUrl: ""
    source: ""
    upstream: ""
    icon: ""
    tools:
      - name: ping_host
      - name: check_website
    secrets: []
    metadata:
      category: monitoring
      tags:
        - uptime
        - ping
        - curl
        - monitoring
        - network
      license: MIT
      owner: local

Create registry.yaml

File Location:

• Windows:
  • %USERPROFILE%.docker\mcp\registry.yaml
• macOS/Linux:
  • ~/.docker/mcp/registry.yaml

Content:

registry:
  uptimecheck:
    ref: ""

3. Configure Claude Desktop

Find Claude Config File File Locations:

• Windows: %APPDATA%\Claude\claude_desktop_config.json
• macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
• Linux: ~/.config/Claude/claude_desktop_config.json

Update Configuration

Replace your config file content with:

{
  "mcpServers": {
    "mcp-toolkit-gateway": {
      "command": "docker",
      "args": [
        "run",
        "-i",
        "--rm",
        "-v", "/var/run/docker.sock:/var/run/docker.sock",
        "-v", "C:/Users/YOUR_USERNAME/.docker/mcp:/mcp",
        "docker/mcp-gateway",
        "--catalog=/mcp/catalogs/docker-mcp.yaml",
        "--catalog=/mcp/catalogs/custom.yaml",
        "--config=/mcp/config.yaml",
        "--registry=/mcp/registry.yaml",
        "--tools-config=/mcp/tools.yaml",
        "--transport=stdio"
      ]
    }
  }
}

⚠️ Important Path Replacements:

• Windows: Replace C:/Users/YOUR_USERNAME with your actual user path (e.g., C:/Users/johnsmith)
• macOS: Replace with /Users/YOUR_USERNAME
• Linux: Replace with /home/YOUR_USERNAME

Launch and Verify

1. Restart Services

1. Close Claude Desktop completely
2. Restart Docker Desktop
3. Wait 30 seconds, then launch Claude Desktop

2. Verify MCP Server

# Check if server is recognized
docker mcp server list

# Should show: uptimecheck
3. Initialize MCP System (if needed)
bash
# If server doesn't appear, reset and reinitialize
docker mcp catalog reset
docker mcp catalog init
docker mcp catalog ls

Web Server Mode

The UptimeCheck server can also run as a standalone web API accessible on port 9000, making it compatible with Open WebUI and other applications that can consume HTTP APIs.

Running as Web API

The server automatically runs in web mode when started, providing both MCP protocol support and HTTP API endpoints.

Start the Web Server

# Build the Docker image
docker build -t mcp_uptimecheck:latest .

# Run the container with port mapping
docker run -d -p 9000:9000 --name mcp-uptimecheck mcp_uptimecheck:latest

# Check if it's running
docker ps
docker logs mcp-uptimecheck

Environment Variables

You can customize the server configuration using environment variables:

# Custom host and port
docker run -d -p 8080:8080 \
  -e MCP_HOST=0.0.0.0 \
  -e MCP_PORT=8080 \
  --name mcp-uptimecheck \
  mcp_uptimecheck:latest

API Endpoints

The web server provides the following HTTP endpoints:

Method	Endpoint	Description
GET	/	Server status and information
GET	/health	Health check with available tools
GET	/ping	Simple ping endpoint (no body required)
GET	/check-website	Simple website check endpoint (no body required)
POST	/tools/list	List all available MCP tools
POST	/tools/call	Execute MCP tools (flexible format)
POST	/ping	Simple ping endpoint (works without body)
POST	/check-website	Simple website check endpoint (works without body)
POST	/debug	Debug endpoint to inspect requests

API Examples

Check server status:

curl http://localhost:9000/

Health check:

curl http://localhost:9000/health

List available tools:

curl -X POST http://localhost:9000/tools/list

Execute ping tool:

curl -X POST http://localhost:9000/tools/call \
  -H "Content-Type: application/json" \
  -d '{"name": "ping_host", "arguments": {"host": "google.com"}}'

Execute website check tool:

curl -X POST http://localhost:9000/tools/call \
  -H "Content-Type: application/json" \
  -d '{"name": "check_website", "arguments": {"url": "https://google.com"}}'

Simple ping endpoint (GET - no body required):

curl http://localhost:9000/ping
curl "http://localhost:9000/ping?host=google.com"

Simple ping endpoint (POST - works without body):

curl -X POST http://localhost:9000/ping
curl -X POST http://localhost:9000/ping \
  -H "Content-Type: application/json" \
  -d '{"host": "google.com"}'

Simple website check endpoint (GET - no body required):

curl http://localhost:9000/check-website
curl "http://localhost:9000/check-website?url=https://google.com"

Simple website check endpoint (POST - works without body):

curl -X POST http://localhost:9000/check-website
curl -X POST http://localhost:9000/check-website \
  -H "Content-Type: application/json" \
  -d '{"url": "https://google.com"}'

Debug endpoint (to see what Open WebUI sends):

curl -X POST http://localhost:9000/debug \
  -H "Content-Type: application/json" \
  -d '{"test": "data"}'

Testing the Web API

You can test the web API using various methods:

Using PowerShell (Windows)

# Test basic endpoints
Invoke-RestMethod -Uri "http://localhost:9000/"
Invoke-RestMethod -Uri "http://localhost:9000/health"

# Test tool execution
$body = '{"name": "ping_host", "arguments": {"host": "google.com"}}'
Invoke-RestMethod -Uri "http://localhost:9000/tools/call" -Method POST -Body $body -ContentType "application/json"

Using curl (Linux/macOS)

# Test basic endpoints
curl http://localhost:9000/
curl http://localhost:9000/health

# Test tool execution
curl -X POST http://localhost:9000/tools/call \
  -H "Content-Type: application/json" \
  -d '{"name": "ping_host", "arguments": {"host": "google.com"}}'

Open WebUI Integration

Open WebUI is an extensible, feature-rich, and user-friendly self-hosted WebUI designed to operate entirely offline. You can integrate the UptimeCheck MCP server with Open WebUI to provide uptime monitoring capabilities.

Install Open WebUI

Using Docker Compose (Recommended)

Create a docker-compose.yml file:

version: '3.8'
services:
  open-webui:
    image: ghcr.io/open-webui/open-webui:main
    container_name: open-webui
    ports:
      - "3000:8080"
    volumes:
      - open-webui:/app/backend/data
    environment:
      - OPENAI_API_BASE_URL=http://localhost:9000
    depends_on:
      - uptimecheck-server

  uptimecheck-server:
    image: mcp_uptimecheck:latest
    container_name: uptimecheck-server
    ports:
      - "9000:9000"
    environment:
      - MCP_HOST=0.0.0.0
      - MCP_PORT=9000

volumes:
  open-webui:

Start the services:

docker-compose up -d

Using Docker Run

# Start the UptimeCheck server
docker run -d -p 9000:9000 --name uptimecheck-server mcp_uptimecheck:latest

# Start Open WebUI
docker run -d -p 3000:8080 \
  -v open-webui:/app/backend/data \
  --name open-webui \
  ghcr.io/open-webui/open-webui:main

Configure MCP Server

The UptimeCheck server is already configured to work with Open WebUI through its HTTP API endpoints. No additional configuration is needed for the server itself.

Add to Open WebUI

1. Access Open WebUI: Open your browser and navigate to http://localhost:3000
2. Create an account or sign in
3. Add the MCP server:
   • Go to Settings → Connected Services
   • Add a new MCP server with the following configuration:
     • Name: UptimeCheck
     • URL: http://uptimecheck-server:9000 (if using docker-compose) or http://localhost:9000
     • API Key: (leave empty if no authentication is required)

Alternative: Use as External Tool

If MCP integration isn't available, you can use the server as an external tool:

1. Create a custom tool in Open WebUI
2. Configure the tool to make HTTP requests to your UptimeCheck server
3. Use the API endpoints to execute ping and website checks

Example Tool Configuration

{
  "name": "ping_host",
  "description": "Ping a host to check network uptime",
  "url": "http://localhost:9000/tools/call",
  "method": "POST",
  "headers": {
    "Content-Type": "application/json"
  },
  "body": {
    "name": "ping_host",
    "arguments": {
      "host": "{{host}}"
    }
  }
}

3. Usage Examples

Once set up, you can use these tools in Claude Desktop conversations:

Ping Host Tool

"Ping 8.8.8.8 to check if it's reachable"

"Check if my server at 192.168.1.100 is up"

"Ping google.com and tell me the results"

Website Checker Tool

"Check if https://google.com is up"

"Is my website https://example.com responding?"

"Test website availability for https://github.com"

Troubleshooting

"No tools available" in Claude Desktop

1. Check tool names match exactly (no backslashes in YAML)
2. Verify file paths in Claude config are correct for your OS
3. Restart both Docker Desktop and Claude Desktop after any config changes
4. Check Docker permissions - ensure Docker can access your user directory

Server not appearing in docker mcp server list

1. Verify custom.yaml syntax with an online YAML validator
2. Check registry.yaml has uptimecheck entry under registry: key
3. Rebuild Docker image if you made code changes:

docker build -t uptimecheck-mcp-server .

Docker MCP plugin issues

# Reinstall Docker MCP plugin
docker plugin rm docker/mcp-plugin:latest
docker plugin install docker/mcp-plugin:latest

# Verify installation
docker mcp version

Permission errors (Linux/macOS)

# Add user to docker group
sudo usermod -aG docker $USER
# Log out and back in

# Fix file permissions
chmod 644 ~/.docker/mcp/catalogs/custom.yaml
chmod 644 ~/.docker/mcp/registry.yaml

Web server not accessible

1. Check if container is running:

   docker ps | grep mcp-uptimecheck
   

2. Check container logs:

   docker logs mcp-uptimecheck
   

3. Verify port mapping:

   # Should show 0.0.0.0:9000->9000/tcp
   docker port mcp-uptimecheck
   

4. Test local connectivity:

   # Test from inside the container
   docker exec mcp-uptimecheck curl http://localhost:9000/health
   
   # Test from host
   curl http://localhost:9000/health
   

5. Check firewall settings (if applicable):

   • Ensure port 9000 is not blocked
   • Check Windows Firewall or iptables rules

Open WebUI integration issues

1. Verify server is accessible from Open WebUI container:

   # If using docker-compose
   docker exec open-webui curl http://uptimecheck-server:9000/health
   
   # If using separate containers
   docker exec open-webui curl http://host.docker.internal:9000/health
   

2. Check network connectivity:

   # Ensure containers can communicate
   docker network ls
   docker network inspect bridge
   

3. Verify Open WebUI configuration:

   • Check the MCP server URL is correct
   • Ensure the server is running before starting Open WebUI
   • Check Open WebUI logs for connection errors

Open WebUI "Request body expected" Error

If you get the error "Request body expected for operation 'call_tool_tools_call_post' but none found":

Solution 1: Use GET Endpoints (Recommended)

The easiest solution is to use GET endpoints that don't require a request body:

For ping:

• Use endpoint: http://localhost:9000/ping (GET)
• Optional: Add query parameter: http://localhost:9000/ping?host=google.com

For website check:

• Use endpoint: http://localhost:9000/check-website (GET)
• Optional: Add query parameter: http://localhost:9000/check-website?url=https://google.com

Solution 2: Use POST Endpoints (No Body Required)

The POST endpoints now work even without a request body:

For ping:

• Use endpoint: http://localhost:9000/ping (POST)
• No body required - defaults to google.com
• Optional: Send {"host": "google.com"}

For website check:

• Use endpoint: http://localhost:9000/check-website (POST)
• No body required - defaults to https://google.com
• Optional: Send {"url": "https://google.com"}

Solution 3: Debug the Request Format

1. Check what Open WebUI is sending:

   curl -X POST http://localhost:9000/debug \
     -H "Content-Type: application/json" \
     -d '{"test": "from_openwebui"}'
   

2. Check server logs:

   docker logs mcp-uptimecheck
   

Solution 4: Configure Open WebUI Tool Correctly

When setting up the tool in Open WebUI, use this configuration:

For Ping Tool:

{
  "name": "ping_host",
  "description": "Ping a host to check network uptime",
  "url": "http://localhost:9000/ping",
  "method": "POST",
  "headers": {
    "Content-Type": "application/json"
  },
  "body": {
    "host": "{{host}}"
  }
}

For Website Check Tool:

{
  "name": "check_website", 
  "description": "Check if a website is up",
  "url": "http://localhost:9000/check-website",
  "method": "POST",
  "headers": {
    "Content-Type": "application/json"
  },
  "body": {
    "url": "{{url}}"
  }
}

Architecture

flowchart TD
    A[Claude Desktop] -->|MCP Gateway| B[UptimeCheck MCP Server]
    E[Open WebUI] -->|HTTP API| B
    F[External Apps] -->|HTTP API| B
    B -->|Execute| C[ping/curl commands]
    D[Docker Desktop MCP System] -.->|Manages| B
    B -->|Port 9000| G[Web API Endpoints]
    
    subgraph "UptimeCheck Server"
        B
        G
        H[/tools/list]
        I[/tools/call]
        J[/health]
        K[/]
    end
    
    G --> H
    G --> I
    G --> J
    G --> K

Development

Local Testing

# Test the server directly
python uptimecheck_server.py

# Test MCP protocol
echo '{"jsonrpc":"2.0","method":"tools/list","id":1}' | python uptimecheck_server.py

Adding New Tools

1. Add function to uptimecheck_server.py with @mcp.tool() decorator
2. Update custom.yaml tools list with new tool name
3. Rebuild Docker image: docker build -t uptimecheck-mcp-server .
4. Restart Claude Desktop

Common File Paths Reference

OS	Claude Config	MCP Config Directory
Windows	%APPDATA%\Claude\claude_desktop_config.json	%USERPROFILE%.docker\mcp\
macOS	~/Library/Application Support/Claude/claude_desktop_config.json	~/.docker/mcp/
Linux	~/.config/Claude/claude_desktop_config.json	~/.docker/mcp/

Quick Reference

Web Server Commands

# Build and run
docker build -t mcp_uptimecheck:latest .
docker run -d -p 9000:9000 --name mcp-uptimecheck mcp_uptimecheck:latest

# Check status
curl http://localhost:9000/health

# Test tools
curl -X POST http://localhost:9000/tools/call \
  -H "Content-Type: application/json" \
  -d '{"name": "ping_host", "arguments": {"host": "google.com"}}'

# Stop and cleanup
docker stop mcp-uptimecheck && docker rm mcp-uptimecheck

Docker Compose for Open WebUI

version: '3.8'
services:
  open-webui:
    image: ghcr.io/open-webui/open-webui:main
    ports: ["3000:8080"]
    volumes: [open-webui:/app/backend/data]
    depends_on: [uptimecheck-server]

  uptimecheck-server:
    image: mcp_uptimecheck:latest
    ports: ["9000:9000"]

volumes:
  open-webui:

Acknowledgements

This MCP server was based on the work of NetworkChuck