3.3 KiB

Raw Blame History

Troubleshooting Claude Configuration

Common issues and solutions for Claude Desktop and Claude Code configurations.

MCP Server Not Loading

Diagnostic checklist:

Validate JSON syntax
Verify command paths are absolute
Check environment variables are set
Review logs: ~/Library/Logs/Claude/mcp*.log
Restart Claude Desktop

Log Locations

macOS

# View all MCP logs
tail -n 20 -f ~/Library/Logs/Claude/mcp*.log

# View specific server logs
tail -f ~/Library/Logs/Claude/mcp-server-SERVERNAME.log

# General MCP connection logs
tail -f ~/Library/Logs/Claude/mcp.log

Windows

Get-Content "$env:APPDATA\Claude\Logs\mcp.log" -Tail 20 -Wait

Common Issues

Working Directory Undefined

Symptom: Server fails with "file not found" errors for relative paths

Solution: Always use absolute paths in configuration

{
  "mcpServers": {
    "server": {
      "command": "/absolute/path/to/command",
      "args": ["--config", "/absolute/path/to/config"]
    }
  }
}

Environment Variables Not Available

Symptom: Server can't access expected environment variables

Solution: Explicitly set variables in env object

{
  "mcpServers": {
    "server": {
      "command": "my-server",
      "env": {
        "API_KEY": "${MY_API_KEY}",
        "HOME": "${HOME}",
        "PATH": "${PATH}"
      }
    }
  }
}

Windows Path Errors

Symptom: "Command not found" or path parsing errors

Solution: Use forward slashes in paths

{
  "command": "C:/Users/name/path/to/command"
}

Server Not Starting

Diagnostic steps:

Test command independently in terminal
Check server logs
Verify all dependencies installed
Confirm API keys are valid

# Test command manually
/usr/local/bin/npx -y @modelcontextprotocol/server-filesystem /tmp

# Check if package exists
npm view @modelcontextprotocol/server-filesystem

JSON Syntax Errors

Symptom: Claude Desktop fails to load any configuration

Solution: Validate JSON before saving

# Validate Claude Desktop config
jq empty ~/Library/Application\ Support/Claude/claude_desktop_config.json

# Validate Claude Code settings
jq empty .claude/settings.json

Validation Commands

Check MCP Server Config

# Extract server names
jq -r '.mcpServers | keys[]' ~/Library/Application\ Support/Claude/claude_desktop_config.json

# Check specific server
jq '.mcpServers["server-name"]' ~/Library/Application\ Support/Claude/claude_desktop_config.json

# Pretty print entire config
jq '.' ~/Library/Application\ Support/Claude/claude_desktop_config.json

Test Server Connection

# Check if server process runs
/path/to/server --help

# Check npm package availability
npx -y @package/server --version

Developer Tools

Enable Chrome DevTools

macOS:

echo '{"allowDevTools": true}' > ~/Library/Application\ Support/Claude/developer_settings.json

Open DevTools: Command-Option-Shift-i

Windows:

echo '{"allowDevTools": true}' > "$env:APPDATA\Claude\developer_settings.json"

Debug Network Issues

With DevTools enabled:

Open DevTools (Cmd+Opt+Shift+i)
Go to Network tab
Look for failed MCP connections
Check Console for error messages

3.3 KiB Raw Blame History