🔧 MCP Fixer Server

A comprehensive diagnostic and repair tool for Model Context Protocol (MCP) servers in Claude Desktop. Automatically detects, diagnoses, and fixes common MCP configuration issues.

🌟 Features

🔍 Configuration Analysis - Validates JSON syntax, paths, and server settings
📊 Server Status Monitoring - Real-time health checks for individual MCP servers
⚙️ Dependency Validation - Ensures Node.js, npm, Python, UV are properly installed
🌐 Port Conflict Detection - Identifies network conflicts on common MCP ports
🔧 Automatic Syntax Fixing - Repairs JSON errors with automatic backup creation
📝 Log File Analysis - Parses MCP logs for error patterns and insights
💡 Smart Suggestions - Provides targeted fix recommendations
🛡️ Safety First - Creates backups before any modifications

🚀 Quick Start

Prerequisites

Node.js 18+ installed
Claude Desktop with MCP support
npm or npx available

Installation

Option 1: NPX (Recommended)

npx @kajdep/mcp-fixer install

Option 2: Global Install

npm install -g @kajdep/mcp-fixer
mcp-fixer install

Option 3: Clone and Install

git clone https://github.com/kajdep/mcp-fixer.git
cd mcp-fixer
npm install
npm run install:claude

Usage

Once installed, simply ask Claude to use the diagnostic tools:

"Claude, can you diagnose my MCP configuration?"
"Claude, check the status of my MCP servers"
"Claude, generate a comprehensive diagnostic report"
"Claude, suggest fixes for my MCP issues"

📋 Available Tools

Tool	Description	Use Case
`diagnose_mcp_config`	Comprehensive configuration analysis	First-line diagnosis
`check_mcp_server_status`	Individual server health checks	Server connectivity issues
`fix_config_syntax`	Automatic JSON syntax repair	Configuration errors
`validate_dependencies`	System dependency verification	Missing tools/packages
`check_port_conflicts`	Port availability scanning	Network conflicts
`generate_diagnostic_report`	Complete system analysis	Full health assessment
`suggest_fixes`	Targeted solution recommendations	Issue resolution

🎯 Common Issues Detected

JSON Syntax Errors - Missing commas, brackets, quotes
Path Issues - Incorrect Windows path escaping
Missing Dependencies - Node.js, npm, Python not found
Port Conflicts - Multiple services using same ports
Server Crashes - MCP servers failing to start
Environment Variables - Missing or empty API keys
Permission Errors - File access and executable permissions

🔧 CLI Usage

# Install to Claude Desktop
mcp-fixer install

# Check installation status
mcp-fixer check

# Remove from Claude Desktop
mcp-fixer uninstall

# Show current configuration
mcp-fixer config

# Run server directly (development)
mcp-fixer run

📊 Example Output

{
  "configPath": "/path/to/claude_desktop_config.json",
  "exists": true,
  "valid": true,
  "issues": [],
  "warnings": [
    {
      "type": "path_escaping",
      "severity": "medium", 
      "server": "filesystem",
      "message": "Potential path escaping issue...",
      "fix": "Ensure Windows paths use double backslashes"
    }
  ],
  "serverCount": 15,
  "recommendations": [
    "Consider disabling unused servers to improve startup time"
  ]
}

🤝 Contributing

We welcome contributions! Please see our Contributing Guide for details.

Quick Contribution Setup

git clone https://github.com/kajdep/mcp-fixer.git
cd mcp-fixer
npm install
npm test

📝 Documentation

🔄 Changelog

See CHANGELOG.md for version history and updates.

📄 License

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

🙏 Acknowledgments

Anthropic for Claude Desktop and MCP

📞 Support

Made with ❤️ for the MCP community"# mcp-fixer"

MCP Fixer