Troubleshooting MCP Server

A Model Context Protocol (MCP) server that provides comprehensive system troubleshooting and diagnostic tools for developers and system administrators. This server enables LLMs to help diagnose system issues, monitor resources, check logs, test connectivity, and more.

Version: 1.0.0 | License: MIT | Python: 3.10+

📋 Table of Contents

• Features
• Project Structure
• Quick Start
• Installation Methods
• Available Tools
• Configuration
• Security
• Development
• Documentation

✨ Features

🖥️ System Information

Get comprehensive details about the operating system, hardware specifications, CPU architecture, memory capacity, and installed software versions.

📊 Resource Monitoring

Real-time monitoring of system resources including:

• CPU usage (overall and per-core)
• Memory utilization (RAM and swap)
• Disk I/O statistics
• Network I/O metrics

📋 Log File Access

Read and analyze system log files with:

• Tail-like functionality to read last N lines
• Pattern-based filtering (similar to grep)
• Common log location discovery
• Support for various log formats

🌐 Network Diagnostics

Test network connectivity with:

• DNS resolution testing
• TCP port connectivity checks
• Connection timing measurements
• Timeout configuration

⚙️ Process Management

Search and monitor running processes:

• Pattern-based process search
• CPU and memory usage per process
• Process status and command line details
• Sorted by resource usage

🔧 Environment Analysis

Inspect system environment including:

• Environment variables (with pattern filtering)
• Installed development tools and versions
• PATH configuration
• Common tool version checks (git, docker, python, node, etc.)

🛡️ Safe Command Execution

Execute whitelisted diagnostic commands with:

• Strict command whitelist for security
• Timeout protection
• Safe diagnostic operations only
• Real-time output capture

📁 Project Structure

troubleshooting_mcp/
├── src/
│   └── troubleshooting_mcp/          # Main package
│       ├── __init__.py               # Package initialization
│       ├── server.py                 # MCP server entry point
│       ├── constants.py              # Shared constants
│       ├── models.py                 # Pydantic input validation models
│       ├── utils.py                  # Utility functions
│       └── tools/                    # Individual diagnostic tools
│           ├── __init__.py           # Tool registration
│           ├── system_info.py        # System information tool
│           ├── resource_monitor.py   # Resource monitoring tool
│           ├── log_reader.py         # Log file reader tool
│           ├── network_diagnostic.py # Network diagnostic tool
│           ├── process_search.py     # Process search tool
│           ├── environment_inspect.py # Environment inspection tool
│           └── safe_command.py       # Safe command execution tool
│
├── tests/                            # Test suite
│   ├── __init__.py
│   └── test_server.py                # Server validation tests
│
├── docs/                             # Documentation
│   ├── QUICKSTART.md                 # Quick start guide
│   ├── EXAMPLES.md                   # Detailed usage examples
│   └── CHANGELOG.md                  # Version history
│
├── config/                           # Configuration files
│   └── claude_desktop_config.example.json # Claude Desktop example config
│
├── troubleshooting_mcp.py            # Backward compatibility entry point
├── setup.py                          # Package setup script
├── pyproject.toml                    # Modern Python project configuration
├── requirements.txt                  # Python dependencies
├── .gitignore                        # Git ignore rules
├── LICENSE                           # MIT License
└── README.md                         # This file

🎯 Key Design Principles

1. Modular Architecture: Each diagnostic tool is in its own module for easy maintenance and testing
2. Clear Separation: Constants, models, utilities, and tools are separated for clarity
3. Backward Compatibility: The root troubleshooting_mcp.py maintains compatibility with existing configurations
4. Installable Package: Can be installed with pip install -e . for system-wide access
5. Type Safety: Uses Pydantic v2 for comprehensive input validation
6. Security First: Strict whitelists, timeout protection, and input validation throughout

🚀 Quick Start

1️⃣ Install Dependencies (1 minute)

# Navigate to the project directory
cd troubleshooting_mcp

# Install required packages
pip install -r requirements.txt

# Or install as a package (recommended)
pip install -e .

2️⃣ Test the Server (1 minute)

# Method 1: Run directly (backward compatible)
python troubleshooting_mcp.py --help

# Method 2: Run as module
python -m troubleshooting_mcp.server --help

# Method 3: If installed as package
troubleshooting-mcp --help

# Run validation tests
python tests/test_server.py

3️⃣ Configure Claude Desktop (2 minutes)

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

{
  "mcpServers": {
    "troubleshooting": {
      "command": "python",
      "args": ["/absolute/path/to/troubleshooting_mcp.py"]
    }
  }
}

Alternative (if installed as package):

{
  "mcpServers": {
    "troubleshooting": {
      "command": "troubleshooting-mcp"
    }
  }
}

4️⃣ Restart Claude Desktop

1. Completely quit Claude Desktop
2. Restart Claude Desktop
3. Look for the 🔌 icon indicating MCP servers are connected

📦 Installation Methods

Method 1: Direct Use (No Installation)

python troubleshooting_mcp.py

Pros: Simple, no installation needed Cons: Not accessible system-wide

Method 2: Editable Install (Development)

pip install -e .
troubleshooting-mcp

Pros: System-wide access, easy to modify, auto-updates Cons: Requires pip install

Method 3: Standard Install (Production)

pip install .
troubleshooting-mcp

Pros: Clean installation, system-wide access Cons: Requires reinstall after changes

Method 4: Module Execution

python -m troubleshooting_mcp.server

Pros: No installation, proper Python module syntax Cons: Requires being in parent directory

🛠 Available Tools

For detailed tool documentation and examples, see docs/EXAMPLES.md.

⚙️ Configuration

Dependencies

• mcp>=1.0.0 - MCP Python SDK with FastMCP framework
• psutil>=5.9.0 - System and process monitoring
• pydantic>=2.0.0 - Input validation

Environment Variables

The server respects standard Python environment variables:

• PYTHONPATH - For module resolution
• PATH - For locating diagnostic commands

Customization

Log Paths: Edit src/troubleshooting_mcp/constants.py:

COMMON_LOG_PATHS = [
    "/var/log/syslog",
    "/custom/app/logs/error.log",
    # Add your custom paths
]

Safe Commands: Edit src/troubleshooting_mcp/constants.py:

SAFE_COMMANDS = {
    "ping", "traceroute", "netstat",
    # Add approved commands only
}

Character Limit: Edit src/troubleshooting_mcp/constants.py:

CHARACTER_LIMIT = 25000  # Adjust as needed

🔒 Security

Command Whitelist

Only pre-approved diagnostic commands can be executed. The whitelist includes common troubleshooting tools but excludes any commands that could:

• Modify system state
• Delete or overwrite files
• Change permissions
• Install software
• Execute arbitrary code

Default Whitelist: ping, traceroute, nslookup, dig, netstat, ss, ip, ifconfig, df, du, free, uptime, uname, lsblk, lsof, whoami, hostname

Timeout Protection

All long-running operations have configurable timeouts:

• Command execution: 30 seconds default, 300 seconds maximum
• Network tests: 5 seconds default, 30 seconds maximum

Permission Handling

• No privilege escalation
• Clear error messages for permission-denied scenarios
• Read-only operations where possible

Input Validation

All inputs are validated using Pydantic models with:

• Type checking
• Range constraints
• Pattern validation
• Whitelist verification

💻 Development

Setting Up Development Environment

# Clone the repository
git clone <repository-url>
cd troubleshooting_mcp

# Create virtual environment (optional but recommended)
python -m venv venv
source venv/bin/activate  # On Windows: venv\Scripts\activate

# Install in editable mode with dev dependencies
pip install -e .

# Run tests
python tests/test_server.py

Adding New Tools

1. Create new tool module in src/troubleshooting_mcp/tools/:

# src/troubleshooting_mcp/tools/my_tool.py
def register_my_tool(mcp):
    @mcp.tool(name="troubleshooting_my_tool", annotations={...})
    async def troubleshooting_my_tool(params: MyInput) -> str:
        # Implementation
        pass

1. Add input model in src/troubleshooting_mcp/models.py:

class MyInput(BaseModel):
    model_config = ConfigDict(str_strip_whitespace=True)
    param: str = Field(..., description="...")

1. Register in tools package src/troubleshooting_mcp/tools/__init__.py:

from .my_tool import register_my_tool

def register_all_tools(mcp):
    # ... existing registrations ...
    register_my_tool(mcp)

Code Style

• Follow PEP 8 style guidelines
• Use type hints where appropriate
• Add comprehensive docstrings to all functions
• Keep tools modular and focused
• Use the shared utility functions

Testing

# Run all tests
python tests/test_server.py

# Test specific functionality
python -c "from src.troubleshooting_mcp import mcp; print('Import successful')"

📚 Documentation

🎯 Example Usage

Once configured in Claude Desktop, try these prompts:

System Diagnostics

"What operating system and hardware does this machine have?"
"Show me current CPU and memory usage"

Log Analysis

"What log files are available on this system?"
"Search nginx error logs for 500 errors in the last 200 lines"

Network Testing

"Can this server reach google.com?"
"Test if port 443 is open on api.example.com"

Process Management

"Is docker running on this system?"
"Show me the top 10 processes by CPU usage"

Environment Inspection

"What development tools are installed?"
"Show me all AWS-related environment variables"

🐛 Troubleshooting

Server Not Appearing in Claude Desktop

1. Check file path is absolute in config
2. Verify JSON syntax (no trailing commas)
3. Check Claude Desktop logs:

• macOS: ~/Library/Logs/Claude/mcp*.log
• Windows: %APPDATA%\Claude\logs\mcp*.log

"Module not found" Error

# Reinstall dependencies
pip install --upgrade -r requirements.txt

# Or use virtual environment
python -m venv venv
source venv/bin/activate  # Windows: venv\Scripts\activate
pip install -e .

"Command not found" Error

# Check Python is in PATH
which python  # macOS/Linux
where python  # Windows

# Or use full path in config
# "command": "/usr/bin/python3"  # macOS/Linux
# "command": "C:/Python310/python.exe"  # Windows

🤝 Contributing

Contributions are welcome! When contributing:

1. Follow the existing code style and modular architecture
2. Add comprehensive docstrings and type hints
3. Include input validation using Pydantic
4. Implement proper error handling
5. Update documentation
6. Test on multiple platforms (Linux, macOS, Windows)

📄 License

This project is licensed under the MIT License - see the LICENSE file for details.

🙏 Acknowledgments

Built using:

• Model Context Protocol (MCP) by Anthropic
• FastMCP - Python MCP SDK
• psutil - System monitoring library
• Pydantic - Data validation

📞 Support

For issues, questions, or suggestions:

• Review the troubleshooting section above
• Check the QUICKSTART guide
• Review EXAMPLES documentation
• Check the MCP documentation: https://modelcontextprotocol.io/

Made for developers and system administrators

Last Updated: 2025-11-05 | Version: 1.0.0