MCP Fixer MCP server

MCP Fixer Server is a comprehensive diagnostic and repair tool for Model Context Protocol (MCP) servers in Claude Desktop. It automatically detects, diagnoses, and fixes common MCP configuration issues, helping you maintain smooth operation of your MCP servers with minimal technical hassle.

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

Installation

Prerequisites

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

Installation Options

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, you can ask Claude to use the diagnostic tools with simple prompts:

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

# 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"
  ]
}

How to install this MCP server

For Claude Code

To add this MCP server to Claude Code, run this command in your terminal:

claude mcp add-json "mcp-fixer" '{"command":"npx","args":["@your-username/mcp-fixer-server","run"]}'

See the official Claude Code MCP documentation for more details.

For Cursor

There are two ways to add an MCP server to Cursor. The most common way is to add the server globally in the ~/.cursor/mcp.json file so that it is available in all of your projects.

If you only need the server in a single project, you can add it to the project instead by creating or adding it to the .cursor/mcp.json file.

Adding an MCP server to Cursor globally

To add a global MCP server go to Cursor Settings > Tools & Integrations and click "New MCP Server".

When you click that button the ~/.cursor/mcp.json file will be opened and you can add your server like this:

{
    "mcpServers": {
        "mcp-fixer": {
            "command": "npx",
            "args": [
                "@your-username/mcp-fixer-server",
                "run"
            ]
        }
    }
}

Adding an MCP server to a project

To add an MCP server to a project you can create a new .cursor/mcp.json file or add it to the existing one. This will look exactly the same as the global MCP server example above.

How to use the MCP server

Once the server is installed, you might need to head back to Settings > MCP and click the refresh button.

The Cursor agent will then be able to see the available tools the added MCP server has available and will call them when it needs to.

You can also explicitly ask the agent to use the tool by mentioning the tool name and describing what the function does.

For Claude Desktop

To add this MCP server to Claude Desktop:

1. Find your configuration file:

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

2. Add this to your configuration file:

{
    "mcpServers": {
        "mcp-fixer": {
            "command": "npx",
            "args": [
                "@your-username/mcp-fixer-server",
                "run"
            ]
        }
    }
}

3. Restart Claude Desktop for the changes to take effect