Service Health MCP Server

🚀 A universal service health monitoring tool for Claude Desktop and MCP-compatible AI assistants

A professional-grade MCP server that enables AI assistants to monitor web services, APIs, and HTTP endpoints with enterprise-level security. Perfect for DevOps, monitoring, and ensuring your services are running smoothly.

🎓 Transparency & Learning

🤖 Built with AI Assistance: This project was created by Natasha in collaboration with Claude Sonnet 4 as a learning exercise. No prior MCP server development experience was required!

📚 Learning Goals Achieved:

• ✅ MCP Protocol Implementation - From zero to working server

• ✅ TypeScript Best Practices - Professional code structure

• ✅ Security-First Development - Enterprise-grade SSRF protection

• ✅ Open Source Standards - Community-ready documentation

• ✅ Real-World Problem Solving - Filling a genuine gap in the MCP ecosystem

💡 For Fellow Learners: If you're new to MCP development or curious about AI-assisted programming, this project demonstrates what's possible when learning with AI guidance. See our development process and contributing guidelines for insights!

Related MCP server: MCP HTTP Client Server

✨ Why This Exists

The Goal: While learning MCP development, I wanted to build something that would be genuinely useful for monitoring services through AI conversations. This MCP server provides a convenient way for Claude (and other AI assistants) to check service health naturally through chat.

What Makes It Useful:

• 🔍 Conversational monitoring - Check services through natural language

• 🛡️ Security-first design with comprehensive SSRF protection

• ⚡ Fast and reliable with detailed diagnostics

• 🎯 Easy to use - works out of the box with Claude Desktop

• 📊 Professional output with actionable information

🚀 Quick Start

Step 1: Install

git clone https://github.com/natashanajdovski/service-health-mcp.git
cd service-health-mcp
npm install
npm run build

Step 2: Configure Claude Desktop

Find your config file:

• Windows: %APPDATA%\Claude\claude_desktop_config.json

• macOS: ~/Library/Application Support/Claude/claude_desktop_config.json

• Linux: ~/.config/Claude/claude_desktop_config.json

Add this configuration:

{
  "mcpServers": {
    "service-health": {
      "command": "node",
      "args": ["C:\\path\\to\\service-health-mcp\\dist\\server.js"],
      "cwd": "C:\\path\\to\\service-health-mcp"
    }
  }
}

Step 3: Restart & Test

1. Completely close and reopen Claude Desktop

2. Test with: "Check if google.com is healthy"

3. See professional health reports instantly! 🎉

🎯 Usage Examples

Basic Health Monitoring

📝 "Check if google.com is healthy"
📝 "Is api.github.com responding properly?"
📝 "Test if my-website.com is up"

Advanced Configurations

📝 "Check if api.example.com/health is healthy with a 15 second timeout"
📝 "Test httpbin.org/post using POST method"
📝 "Check if my-api.com returns 201 status code"

DevOps & Monitoring

📝 "Check if our production API is responding normally"
📝 "Test all our microservices for health"
📝 "Monitor our CDN endpoints"

📊 Sample Output

✅ **Health Check Result**

**URL:** https://api.github.com
**Status:** HEALTHY
**Response Time:** 127ms  
**HTTP Status:** 200 (OK)
**Message:** Endpoint is healthy (200) - 127ms response time
**Checked At:** 2024-07-24T21:30:00.000Z

**Interpretation:**
🎉 The endpoint is working perfectly! No issues detected.

For unhealthy services:

❌ **Health Check Result**

**URL:** https://down-service.com
**Status:** UNHEALTHY
**Response Time:** 5000ms
**Message:** Network error: Connection timeout
**Checked At:** 2024-07-24T21:30:00.000Z

**Interpretation:**
🚨 The endpoint has issues and may be down or misconfigured. Investigation needed.

🛠️ Features

🔍 Health Monitoring

• ✅ HTTP/HTTPS endpoint testing

• ✅ Response time measurement

• ✅ Status code validation

• ✅ Custom headers support

• ✅ Multiple HTTP methods

• ✅ Configurable timeouts (1-30s)

🛡️ Enterprise Security

• ✅ SSRF attack prevention

• ✅ Internal network blocking

• ✅ Input validation & sanitization

• ✅ Protocol restrictions (HTTP/HTTPS only)

• ✅ Port filtering & safe defaults

• ✅ Zero credential exposure

⚡ Performance

• ✅ Sub-second response times

• ✅ Efficient connection handling

• ✅ Minimal resource usage

• ✅ Non-blocking async operations

• ✅ Optimized error handling

• ✅ Smart retry logic

🔧 Developer Experience

• ✅ Full TypeScript support

• ✅ Professional error messages

• ✅ Comprehensive logging

• ✅ Easy MCP integration

• ✅ Hot reload development

• ✅ Extensive documentation

🛡️ Security

This MCP server implements enterprise-grade security to prevent attacks:

🚨 SSRF (Server-Side Request Forgery) Protection

❌ BLOCKED: localhost, 127.0.0.1
❌ BLOCKED: 192.168.x.x, 10.x.x.x, 172.16-31.x.x  
❌ BLOCKED: 169.254.169.254 (cloud metadata)
❌ BLOCKED: Non-HTTP protocols (ftp, file, etc.)
✅ ALLOWED: Public HTTP/HTTPS endpoints only

🔒 Input Validation

• URL Format: RFC-compliant validation

• Parameter Types: Strict type checking with Zod

• Timeout Bounds: 1-30 second limits

• Method Restrictions: GET, POST, PUT, DELETE only

• Port Filtering: Standard web ports (80, 443, 8080, 8443)

🛡️ Safe Defaults

• 10-second timeout (prevents hanging)

• GET method (least intrusive)

• No credential storage (stateless operation)

• Minimal error details (no information leakage)

🔧 Development

Prerequisites

• Node.js 18+

• TypeScript 5+

• npm or yarn

Development Commands

npm run dev    # 🔄 Hot reload development
npm run build  # 🏗️ Production build  
npm run start  # 🚀 Run built version
npm run clean  # 🧹 Clean build files

Testing with MCP Inspector

npx @modelcontextprotocol/inspector src/server.ts

Project Structure

service-health-mcp/
├── src/
│   ├── server.ts           # 🎯 Main MCP server
│   ├── health/
│   │   └── http-checker.ts # 🔍 Core health logic  
│   ├── security/
│   │   └── url-validator.ts # 🛡️ SSRF protection
│   └── tools/
│       └── check-http.ts   # 🛠️ MCP tool interface
├── dist/                   # 📦 Compiled JavaScript
├── docs/                   # 📚 Documentation
└── package.json           # 📋 Project config

📚 API Reference

check_http_endpoint

Description: Check if an HTTP/HTTPS endpoint is healthy and responsive.

Parameters

Example Request

{
  "url": "https://api.example.com/health",
  "method": "GET", 
  "timeout": 15000,
  "expectedStatus": 200,
  "headers": {
    "User-Agent": "Health-Checker/1.0",
    "Accept": "application/json"
  }
}

Response Format

{
  status: "healthy" | "unhealthy" | "warning";
  responseTime: number;          // milliseconds
  statusCode?: number;           // HTTP status code
  message: string;               // Human-readable description
  details: {
    url: string;
    timestamp: string;           // ISO 8601 format
    error?: string;              // Error details if applicable
  }
}

🔄 Troubleshooting

❓ Tool Not Appearing in Claude Desktop

Problem: Claude doesn't recognize the health check tool.

Solutions:

1. Verify config syntax: Use a JSON validator

2. Check file paths: Use absolute paths in config

3. Restart completely: Close Claude Desktop entirely, then reopen

4. Test build: Run npm run build and check for errors

5. Check permissions: Ensure Node.js can read the files

🌐 Network Connection Issues

Problem: Getting network errors or timeouts.

❌ Network error: Client network socket disconnected

Solutions:

• Service may be down: Try checking in browser first

• HTTPS issues: Try HTTP version of the URL

• Firewall: Check if your network blocks the service

• DNS: Verify the domain resolves correctly

🔒 Security Restriction Messages

Problem: URLs being blocked for security reasons.

❌ Access to internal networks and localhost is not allowed

This is intentional! The security system is working correctly:

• For local testing: Use browser or curl directly

• For monitoring: Use external, publicly accessible URLs only

• For internal services: Deploy monitoring within your network

⚡ Performance Issues

Problem: Slow response times or timeouts.

Solutions:

• Increase timeout: Use 15-30 second timeouts for slow services

• Check network: Test connectivity to the target service

• Reduce load: Avoid checking too many endpoints simultaneously

🤝 Contributing

We welcome contributors of all skill levels! This project was built by a learner with AI assistance, and we're excited to grow the community.

🌟 Ways to Contribute

• 🐛 Bug Reports: Found an issue? Please report it!

• ✨ Feature Requests: Ideas for new capabilities?

• 📖 Documentation: Help improve our guides

• 🔧 Code: Submit pull requests for enhancements

• 🎓 Learning: Share your experience using this project

🚀 Getting Started

1. Fork the repository

2. Clone your fork: git clone https://github.com/yourusername/service-health-mcp.git

3. Create branch: git checkout -b feature/amazing-feature

4. Make changes and test thoroughly

5. Commit: git commit -m "Add amazing feature"

6. Push: git push origin feature/amazing-feature

7. Open Pull Request with detailed description

📋 Contribution Guidelines

• Code Style: Follow existing TypeScript patterns

• Security: Maintain SSRF protection standards

• Tests: Add tests for new features

• Documentation: Update docs for any changes

• Commit Messages: Use clear, descriptive commits

See CONTRIBUTING.md for detailed guidelines.

🗺️ Roadmap

🎯 Phase 1: Core Stability (Current)

• ✅ HTTP/HTTPS health checking

• ✅ Enterprise security (SSRF protection)

• ✅ Claude Desktop integration

• ✅ Professional documentation

🎯 Phase 2: Database Support (Next)

• 🔄 PostgreSQL health checking

• 🔄 MySQL/MariaDB support

• 🔄 Redis connectivity testing

• 🔄 MongoDB health monitoring

🎯 Phase 3: Advanced Features

• 📊 Multi-service dashboards

• 📈 Health history tracking

• 🔔 Webhook notifications

• ⏰ Scheduled monitoring

🎯 Phase 4: Enterprise

• ☁️ Cloud integration (AWS, Azure, GCP)

• 🐳 Docker containerization

• 🔐 Authentication support

• 📊 Prometheus metrics export

💡 Community Input Welcome! Open an issue to suggest features or vote on priorities.

📜 License

MIT License - see LICENSE file for details.

TL;DR: You can use, modify, and distribute this project freely. Just include the license notice.

🙏 Acknowledgments

• 🤖 Anthropic for Claude AI assistance and the MCP protocol

• 🏗️ MCP Community for pioneering this ecosystem

• 🌟 Open Source Contributors who make projects like this possible

• 📚 Learning Community for encouraging AI-assisted development

📞 Support & Community

📚 Documentation

• Quick Start Guide - Complete installation instructions

• Development Setup - For developers new to MCP

• API Reference - Complete technical documentation

• Security Details - Security considerations and best practices

💬 Get Help

• 🐛 Issues - Bug reports and feature requests

• 💭 Discussions - Community Q&A and ideas

🔗 Connect

• 👩‍💻 GitHub Profile - Follow for updates

🚀 Built with ❤️, TypeScript, and Claude AI | Making service monitoring accessible to everyone

⭐ Star this repo if it helped you! ⭐