<img src="assets/favicon.png" alt="Service Health MCP Server" width="32" height="32"> Service Health MCP Server

🚀 The first 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!

---

✨ 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

<table> <tr> <td width="50%">

🔍 Health Monitoring

• ✅ HTTP/HTTPS endpoint testing
• ✅ Response time measurement
• ✅ Status code validation
• ✅ Custom headers support
• ✅ Multiple HTTP methods
• ✅ Configurable timeouts (1-30s)

</td> <td width="50%">

🛡️ Enterprise Security

• ✅ SSRF attack prevention
• ✅ Internal network blocking
• ✅ Input validation & sanitization
• ✅ Protocol restrictions (HTTP/HTTPS only)
• ✅ Port filtering & safe defaults
• ✅ Zero credential exposure

</td> </tr> <tr> <td width="50%">

⚡ Performance

• ✅ Sub-second response times
• ✅ Efficient connection handling
• ✅ Minimal resource usage
• ✅ Non-blocking async operations
• ✅ Optimized error handling
• ✅ Smart retry logic

</td> <td width="50%">

🔧 Developer Experience

• ✅ Full TypeScript support
• ✅ Professional error messages
• ✅ Comprehensive logging
• ✅ Easy MCP integration
• ✅ Hot reload development
• ✅ Extensive documentation

</td> </tr> </table>

---

🛡️ 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

Parameter	Type	Required	Default	Description
url	string	✅ Yes	-	The URL to check (e.g., https://google.com)
method	"GET" | "POST" | "PUT" | "DELETE"	❌ No	"GET"	HTTP method to use
timeout	number	❌ No	10000	Request timeout in milliseconds (1000-30000)
expectedStatus	number	❌ No	200	Expected HTTP status code (100-599)
headers	Record<string, string>	❌ No	{}	Optional HTTP headers

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

---

<div align="center">

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

⭐ Star this repo if it helped you! ⭐

</div>