Troubleshooting Common MCP Server Issues

Issue 1: Server Not Connecting

Symptoms: No hammer icon in Claude Desktop. Tools not available. Server not listed.

Fix: Check Your JSON Config

The #1 cause of connection failures is invalid JSON. Common mistakes:

// ❌ Trailing comma (invalid JSON)
{
  "mcpServers": {
    "filesystem": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-filesystem", "/path"],
    }  // ← trailing comma!
  }
}

// ✅ Valid JSON
{
  "mcpServers": {
    "filesystem": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-filesystem", "/path"]
    }
  }
}

Quick fix: Paste your config into jsonlint.com to validate.

Fix: Verify Node.js Installation

# Check if Node.js is installed and in PATH
node --version    # Should show v18+ 
npx --version     # Should return a version number

If these commands fail, install Node.js. On Windows, you may need to restart your computer after installation for PATH changes to take effect.

Fix: Restart Claude Desktop

After any config change, fully quit Claude Desktop (don't just close the window) and reopen it. On macOS, use Cmd+Q. On Windows, check the system tray.

Issue 2: "Command Not Found" Errors

Symptoms: Server fails with "ENOENT" or "command not found" in logs.

Fix: Use Full Paths

Claude Desktop may not have the same PATH as your terminal. Use absolute paths:

// ❌ Relies on PATH
"command": "npx"

// ✅ Full path (find it with `which npx` or `where npx`)
"command": "/usr/local/bin/npx"         // macOS/Linux
"command": "C:\\Program Files\\nodejs\\npx.cmd"  // Windows

Fix: Windows-Specific npx Issues

On Windows, use npx.cmd instead of npx:

{
  "command": "npx.cmd",
  "args": ["-y", "@modelcontextprotocol/server-filesystem", "C:\\Users\\you\\Documents"]
}

Issue 3: Server Connects but Tools Don't Work

Symptoms: Hammer icon appears, tools are listed, but calls fail with errors.

Fix: Check Environment Variables

Many servers need API keys via environment variables:

{
  "github": {
    "command": "npx",
    "args": ["-y", "@modelcontextprotocol/server-github"],
    "env": {
      "GITHUB_PERSONAL_ACCESS_TOKEN": "ghp_xxxxxxxxxxxx"
    }
  }
}

Verify your tokens are valid and have the required scopes.

Fix: Check File/Directory Permissions

For filesystem servers, ensure the configured directory exists and is readable:

# Check if the path exists
ls -la /path/to/your/directory

# Check permissions
stat /path/to/your/directory

Issue 4: Timeouts

Symptoms: Tools start executing but then fail with timeout errors.

Fix: Check Network Connectivity

If the server calls external APIs (GitHub, databases, etc.), verify you can reach them:

# Test GitHub API access
curl https://api.github.com/user -H "Authorization: token YOUR_TOKEN"

# Test database connectivity
pg_isready -h localhost -p 5432

Fix: Check for Slow Operations

Some operations naturally take time (large file searches, complex queries). If your server is timing out on large operations, consider:

• Reducing the scope of operations (search smaller directories)
• Adding pagination to results
• Increasing timeout settings if your host supports it

Issue 5: Python Server Problems

Symptoms: Python-based MCP servers fail to start.

Fix: Use the Right Python

// ❌ System python might be wrong version
"command": "python"

// ✅ Be explicit about Python version
"command": "python3"

// ✅ Or use uvx for managed environments
"command": "uvx",
"args": ["mcp-server-name"]

Fix: Install Dependencies

# If using pip
pip install mcp-server-name

# If using uvx (recommended)
uvx mcp-server-name --help

Issue 6: Multiple Server Conflicts

Symptoms: Some servers work but others don't, or servers stop working when new ones are added.

Fix: Isolate the Problem

1. Comment out all servers except one
2. Test that single server
3. Add servers back one at a time
4. The server that breaks things is the culprit

Fix: Check for Port Conflicts

If using servers with SSE transport, ensure they're not competing for the same port.

Diagnostic Steps

When nothing else works, follow this systematic approach:

1. Check logs: ~/Library/Logs/Claude/mcp*.log (macOS) or %APPDATA%\Claude\logs\ (Windows)
2. Test the command manually: Run the exact command from your config in a terminal
3. Validate JSON: Paste config into a JSON validator
4. Check versions: node --version, python3 --version
5. Try a known-good server: Install the official filesystem server to verify your setup works
6. Check GitHub issues: Search the server's GitHub repo for similar problems

Getting Help

• MCP Hub Directory — Each server listing includes compatibility info and links
• MCP GitHub — Official repos with issue trackers
• Server-specific repos — Check the individual server's GitHub for issues and discussions

FAQ

Why can't Claude Desktop find my MCP server?

The most common causes are: invalid JSON in config file, wrong path to the server executable, Node.js not installed or not in PATH, or not restarting Claude Desktop after config changes.

MCP server keeps timing out — what do I do?

Timeouts usually mean the server is taking too long to respond. Check if the underlying service (database, API) is reachable. For slow operations, consider implementing progress notifications.

How do I check MCP server logs?

Claude Desktop logs MCP activity to ~/Library/Logs/Claude/mcp*.log on macOS and %APPDATA%\Claude\logs\ on Windows. You can also add console.error() logging in custom servers.