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
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
- Completely close and reopen Claude Desktop
- Test with:
"Check if google.com is healthy" - 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
- ✅ 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
- 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"
}
}
{
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
Problem: Claude doesn't recognize the health check tool.
Solutions:
- Verify config syntax: Use a JSON validator
- Check file paths: Use absolute paths in config
- Restart completely: Close Claude Desktop entirely, then reopen
- Test build: Run
npm run build and check for errors - 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
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
- Fork the repository
- Clone your fork:
git clone https://github.com/yourusername/service-health-mcp.git - Create branch:
git checkout -b feature/amazing-feature - Make changes and test thoroughly
- Commit:
git commit -m "Add amazing feature" - Push:
git push origin feature/amazing-feature - 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
💬 Get Help
🔗 Connect
🚀 Built with ❤️, TypeScript, and Claude AI | Making service monitoring accessible to everyone
⭐ Star this repo if it helped you! ⭐