169 lines
3.3 KiB
Markdown
169 lines
3.3 KiB
Markdown
# Troubleshooting Claude Configuration
|
|
|
|
Common issues and solutions for Claude Desktop and Claude Code configurations.
|
|
|
|
## MCP Server Not Loading
|
|
|
|
**Diagnostic checklist:**
|
|
|
|
1. Validate JSON syntax
|
|
2. Verify command paths are absolute
|
|
3. Check environment variables are set
|
|
4. Review logs: `~/Library/Logs/Claude/mcp*.log`
|
|
5. Restart Claude Desktop
|
|
|
|
## Log Locations
|
|
|
|
### macOS
|
|
|
|
```bash
|
|
# 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
|
|
|
|
```powershell
|
|
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
|
|
|
|
```json
|
|
{
|
|
"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
|
|
|
|
```json
|
|
{
|
|
"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
|
|
|
|
```json
|
|
{
|
|
"command": "C:/Users/name/path/to/command"
|
|
}
|
|
```
|
|
|
|
### Server Not Starting
|
|
|
|
**Diagnostic steps:**
|
|
|
|
1. Test command independently in terminal
|
|
2. Check server logs
|
|
3. Verify all dependencies installed
|
|
4. Confirm API keys are valid
|
|
|
|
```bash
|
|
# 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
|
|
|
|
```bash
|
|
# 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
|
|
|
|
```bash
|
|
# 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
|
|
|
|
```bash
|
|
# Check if server process runs
|
|
/path/to/server --help
|
|
|
|
# Check npm package availability
|
|
npx -y @package/server --version
|
|
```
|
|
|
|
## Developer Tools
|
|
|
|
### Enable Chrome DevTools
|
|
|
|
**macOS:**
|
|
|
|
```bash
|
|
echo '{"allowDevTools": true}' > ~/Library/Application\ Support/Claude/developer_settings.json
|
|
```
|
|
|
|
Open DevTools: `Command-Option-Shift-i`
|
|
|
|
**Windows:**
|
|
|
|
```powershell
|
|
echo '{"allowDevTools": true}' > "$env:APPDATA\Claude\developer_settings.json"
|
|
```
|
|
|
|
### Debug Network Issues
|
|
|
|
With DevTools enabled:
|
|
1. Open DevTools (`Cmd+Opt+Shift+i`)
|
|
2. Go to Network tab
|
|
3. Look for failed MCP connections
|
|
4. Check Console for error messages
|