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+

✨ 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

Modular Architecture: Each diagnostic tool is in its own module for easy maintenance and testing
Clear Separation: Constants, models, utilities, and tools are separated for clarity
Backward Compatibility: The root troubleshooting_mcp.py maintains compatibility with existing configurations
Installable Package: Can be installed with pip install -e . for system-wide access
Type Safety: Uses Pydantic v2 for comprehensive input validation
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

Completely quit Claude Desktop
Restart Claude Desktop
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

| Tool | Description | Example Usage | | ------------------------------------------- | ----------------------------------- | ------------------------------- | | troubleshooting_get_system_info | Get comprehensive system details | "What are the system specs?" | | troubleshooting_monitor_resources | Monitor CPU, memory, disk, network | "Show current resource usage" | | troubleshooting_read_log_file | Read and filter log files | "Show last 100 lines of syslog" | | troubleshooting_test_network_connectivity | Test host/port connectivity | "Can I reach google.com?" | | troubleshooting_search_processes | Search running processes | "Is nginx running?" | | troubleshooting_inspect_environment | Check environment variables & tools | "What dev tools are installed?" | | troubleshooting_execute_safe_command | Run whitelisted commands | "Run df -h to check disk space" |

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

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

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

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

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

| Document | Description | | -------------------------------------------------------------------------------------- | ---------------------------------------- | | README.md | This file - Overview and getting started | | docs/QUICKSTART.md | 5-minute quick start guide | | docs/EXAMPLES.md | Detailed usage examples for each tool | | docs/CHANGELOG.md | Version history and changes | | config/claude_desktop_config.example.json | Example Claude Desktop configuration |

🎯 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"