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 operations with your Claude Desktop MCP integrations.

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

Installation

You can install MCP Fixer Server in three different ways:

Using NPX (Recommended)

npx @your-username/mcp-fixer-server install

Global Install

npm install -g @your-username/mcp-fixer-server
mcp-fixer install

Clone and Install

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

Prerequisites

Before installing, ensure you have:

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

Usage

Basic Commands

Once installed, you can interact with 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"

CLI Commands

MCP Fixer Server also provides a command-line interface:

# 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

Available Diagnostic Tools

The following tools are available through the MCP Fixer Server:

• diagnose_mcp_config - Comprehensive configuration analysis for first-line diagnosis
• check_mcp_server_status - Individual server health checks for connectivity issues
• fix_config_syntax - Automatic JSON syntax repair for configuration errors
• validate_dependencies - System dependency verification for missing tools/packages
• check_port_conflicts - Port availability scanning for network conflicts
• generate_diagnostic_report - Complete system analysis for full health assessment
• suggest_fixes - Targeted solution recommendations for issue resolution

Common Issues Detected

MCP Fixer Server can identify and fix various issues including:

• 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

Example Output

When running diagnostics, you'll receive structured output similar to:

{
  "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 the mcpServers section:

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

3. Restart Claude Desktop for the changes to take effect