How to Debug an MCP Server

Step 1 — find and read the logs

Every MCP server in Claude Desktop writes its output to a dedicated log file. These are the most useful debugging artifact available.

# macOS - list all MCP logs
ls ~/Library/Logs/Claude/mcp*.log

# macOS - follow a specific server log in real time
tail -f ~/Library/Logs/Claude/mcp-server-filesystem.log

# Windows (PowerShell)
ls "$env:APPDATA\Claude\logs\mcp*.log"
Get-Content "$env:APPDATA\Claude\logs\mcp-server-filesystem.log" -Tail 50 -Wait

# Linux
ls ~/.config/Claude/logs/mcp*.log
tail -f ~/.config/Claude/logs/mcp-server-filesystem.log

The log file name corresponds to the server key in your mcpServers config. If you named the server "myserver", the log is mcp-server-myserver.log.

Step 2 — interpret error patterns

Step 3 — test the server manually

Run the exact command from your config directly in a terminal. This bypasses Claude Desktop and shows you the raw server output without any filtering:

# Run the server directly (use the same command and args as in your config)
/usr/local/bin/npx -y @modelcontextprotocol/server-filesystem /Users/you/projects

# For Python/uvx servers
/Users/you/.local/bin/uvx mcp-server-git --repository /Users/you/myrepo

A healthy server will start and then wait quietly for input (it speaks MCP over stdio). An error will print immediately. This confirms whether the problem is in the server itself or in how Claude Desktop is invoking it.

If the server errors here, fix the underlying issue first — there is no point debugging the Claude Desktop integration until the server runs cleanly on its own.

Step 4 — use MCP Inspector

MCP Inspector is the official interactive testing tool for MCP servers. It sends real MCP protocol messages and shows the JSON responses:

# Install and run in one command
npx @modelcontextprotocol/inspector /usr/local/bin/npx -y @modelcontextprotocol/server-filesystem /tmp

# For uvx servers
npx @modelcontextprotocol/inspector /Users/you/.local/bin/uvx mcp-server-git --repository /tmp/test

Inspector opens a browser UI (usually at http://localhost:5173). From there you can:

• Complete the MCP initialize handshake
• Call tools/list to see what tools the server exposes
• Call tools/call with specific arguments to test individual tools
• See the raw JSON request and response for each call

This is the fastest way to verify a server is working correctly without involving Claude Desktop at all.

Step 5 — check the environment

Many MCP servers fail because they have different environment variables in Claude Desktop vs your terminal. To debug this, add temporary verbose logging to the server command:

# Add env inspection to a wrapper script (macOS/Linux)
# Create /tmp/mcp-debug.sh:
#!/bin/bash
echo "PATH=$PATH" >> /tmp/mcp-env.log
echo "HOME=$HOME" >> /tmp/mcp-env.log
env >> /tmp/mcp-env.log
exec /usr/local/bin/npx -y @modelcontextprotocol/server-filesystem "$@"

Or compare the environment directly: set "command": "/usr/bin/env" and "args": ["bash", "-c", "env > /tmp/mcp-env.log && exec /usr/local/bin/npx ..."] temporarily in your config to log the full environment that Claude Desktop provides.

What to look for in the env diff between terminal and Claude Desktop:

• Missing PATH entries (the core reason for spawn ENOENT)
• Missing HOME (some servers use it to locate config files)
• Missing API key env vars (if you set them in shell profile instead of the MCP config's env block)

Step 6 — isolate to one server

If multiple servers are failing, isolate the problem by temporarily reducing your config to a single server:

{
  "mcpServers": {
    "filesystem": {
      "command": "/usr/local/bin/npx",
      "args": ["-y", "@modelcontextprotocol/server-filesystem", "/tmp"]
    }
  }
}

If this works, add servers back one at a time until you find which one is causing the problem. One failing server with a bad startup should not prevent others from working, but config JSON errors or PATH issues can sometimes cascade.

FAQ