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!

✨ 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

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

⚡ 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

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:

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

⚡ 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

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

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! ⭐

Service Health MCP Server

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

🎓 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

✨ Why This Exists

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

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

⚡ 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

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:

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

⚡ 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

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

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! ⭐