Troubleshooting Guide

This comprehensive guide helps you diagnose and resolve common issues with Trello Desktop MCP.

Quick Diagnostic Checklist

Start with these quick checks:

• Claude Desktop is completely restarted (not just closed)
• Trello API credentials are valid and have proper permissions
• File path in Claude Desktop config points to dist/index.js
• Project was built successfully (npm run build)
• Configuration file uses absolute paths
• JSON configuration syntax is valid

Common Issues and Solutions

Installation and Setup Issues

Issue: "No Trello tools available" in Claude Desktop

Symptoms:

• Claude Desktop doesn't show any Trello tools
• No response when asking about Trello functionality
• MCP connection appears inactive

Possible Causes and Solutions:

1. Path Configuration Issue

   // ❌ Incorrect - relative path
   "args": ["./dist/index.js"]
   
   // ✅ Correct - absolute path
   "args": ["/Users/username/Projects/trello-desktop-mcp/dist/index.js"]
   

2. Build Missing or Failed

   # Check if dist directory exists
   ls -la dist/
   
   # If missing, rebuild
   npm run clean
   npm run build
   
   # Verify build success
   ls -la dist/index.js
   

3. Claude Desktop Not Restarted

   • Completely quit Claude Desktop (Cmd+Q on Mac, not just close window)
   • Wait 5 seconds
   • Restart Claude Desktop
   • Wait for full startup before testing

4. Configuration File Location

   # Verify config file location
   # macOS
   ls -la ~/Library/Application\ Support/Claude/claude_desktop_config.json
   
   # Windows
   dir %APPDATA%\Claude\claude_desktop_config.json
   
   # Linux
   ls -la ~/.config/Claude/claude_desktop_config.json
   

5. JSON Syntax Errors

   # Validate JSON syntax
   python -m json.tool ~/Library/Application\ Support/Claude/claude_desktop_config.json
   
   # Or use online JSON validator
   

Issue: "Invalid credentials" or Authentication Failures

Symptoms:

• Error messages about invalid API key or token
• 401 Unauthorized responses
• "Permission denied" errors

Solutions:

1. Verify API Credentials

   # Test credentials with curl
   curl "https://api.trello.com/1/members/me?key=YOUR_KEY&token=YOUR_TOKEN"
   
   # Should return your user information
   

2. Regenerate Trello Token

   • Visit https://trello.com/app-key
   • Generate new token with:
     • Read access: Yes
     • Write access: Yes
     • Expiration: Never (recommended for personal use)

3. Check Token Permissions

   • Ensure token has read/write permissions
   • Verify token hasn't expired
   • Confirm token is associated with correct Trello account

4. Update Configuration

   {
     "mcpServers": {
       "trello": {
         "command": "node",
         "args": ["/absolute/path/to/dist/index.js"],
         "env": {
           "TRELLO_API_KEY": "your-new-api-key",
           "TRELLO_TOKEN": "your-new-token"
         }
       }
     }
   }
   

Runtime Issues

Issue: "Rate limit exceeded" Errors

Symptoms:

• HTTP 429 errors
• Delays in tool responses
• "Too many requests" messages

Solutions:

1. Understand Rate Limits

   • Trello API allows 300 requests per 10 seconds per API key
   • Rate limits reset every 10 seconds
   • MCP server includes automatic retry logic

2. Reduce Request Frequency

   # Instead of multiple rapid requests
   "Show me board 1"
   "Show me board 2" 
   "Show me board 3"
   
   # Use batch requests
   "Show me details for all my boards"
   

3. Wait for Rate Limit Reset

   • Rate limits automatically reset
   • MCP server will retry automatically
   • Wait 10-15 seconds before retrying manually

Issue: "Resource not found" (404 Errors)

Symptoms:

• "Board not found" errors
• "Card not found" errors
• "List not found" errors

Solutions:

1. Verify Resource IDs

   # Board IDs are 24-character hex strings
   # Valid: 507f1f77bcf86cd799439011
   # Invalid: board_123 or short-id
   

2. Check Access Permissions

   • Ensure you have access to the board/card
   • Verify the resource hasn't been deleted
   • Confirm you're a member of private boards

3. Use Search to Find Resources

   # Find boards by name
   "Search for boards named 'Project Management'"
   
   # Find cards by title
   "Search for cards containing 'bug fix'"
   

Issue: Network Connection Problems

Symptoms:

• Timeout errors
• "Unable to reach Trello API" messages
• Intermittent connection failures

Solutions:

1. Check Internet Connection

   # Test basic connectivity
   ping api.trello.com
   
   # Test HTTPS access
   curl -I https://api.trello.com/1/members/me
   

2. Firewall and Proxy Issues

   • Check corporate firewall settings
   • Verify proxy configuration
   • Ensure HTTPS traffic is allowed

3. DNS Resolution

   # Test DNS resolution
   nslookup api.trello.com
   

Performance Issues

Issue: Slow Response Times

Symptoms:

• Long delays before tool responses
• Timeouts on large operations
• Poor performance with large boards

Solutions:

1. Optimize Request Scope

   # Instead of broad requests
   "Show me everything about my board"
   
   # Use specific requests
   "Show me just the lists in my board"
   "Show me cards in the 'To Do' list"
   

2. Use Filtering Options

   # Filter by status
   "Show me only open cards in my board"
   
   # Limit results
   "Show me the first 20 cards in my board"
   

3. Break Down Large Operations

   # Instead of batch operations
   "Update 50 cards at once"
   
   # Process in smaller batches
   "Update cards in the 'To Do' list"
   "Update cards in the 'In Progress' list"
   

Data and Content Issues

Issue: Missing or Incomplete Data

Symptoms:

• Cards missing expected fields
• Empty board responses
• Incomplete member information

Solutions:

1. Request Detailed Information

   # Basic request
   "Show me my board"
   
   # Detailed request
   "Show me my board with all lists, cards, members, and labels"
   

2. Check Data Availability

   • Verify data exists in Trello web interface
   • Confirm permissions to access detailed data
   • Check if data was recently modified

3. Use Specific Detail Tools

   # Get comprehensive card details
   "Show me complete details for card 'Task Name'"
   
   # Get member information
   "Show me information about @username"
   

Issue: Character Encoding Problems

Symptoms:

• Special characters display incorrectly
• Unicode symbols broken
• Non-English text garbled

Solutions:

1. Verify Environment Settings

   # Check locale settings
   echo $LANG
   
   # Should be UTF-8 compatible (e.g., en_US.UTF-8)
   

2. Update Terminal/Console Settings

   • Ensure Claude Desktop uses UTF-8 encoding
   • Check system locale configuration

Advanced Troubleshooting

Log Analysis

Enable Debug Logging

// Add to Claude Desktop config
{
  "mcpServers": {
    "trello": {
      "command": "node",
      "args": ["/path/to/dist/index.js"],
      "env": {
        "TRELLO_API_KEY": "your-key",
        "TRELLO_TOKEN": "your-token",
        "LOG_LEVEL": "debug"
      }
    }
  }
}

Log File Locations

# macOS
tail -f ~/Library/Logs/Claude/mcp-server-trello.log

# Windows  
type %APPDATA%\Claude\Logs\mcp-server-trello.log

# Linux
tail -f ~/.config/Claude/Logs/mcp-server-trello.log

Common Log Patterns

# Successful operations
grep "successful" mcp-server-trello.log

# Error patterns
grep "error\|ERROR" mcp-server-trello.log

# Rate limit issues
grep "rate limit\|429" mcp-server-trello.log

# Network issues
grep "timeout\|ENOTFOUND" mcp-server-trello.log

Manual API Testing

Test API Access Directly

# Test basic API access
curl -X GET \
  "https://api.trello.com/1/members/me/boards?key=YOUR_KEY&token=YOUR_TOKEN" \
  -H "Accept: application/json"

# Test specific board access
curl -X GET \
  "https://api.trello.com/1/boards/BOARD_ID?key=YOUR_KEY&token=YOUR_TOKEN" \
  -H "Accept: application/json"

# Test card creation
curl -X POST \
  "https://api.trello.com/1/cards?key=YOUR_KEY&token=YOUR_TOKEN" \
  -H "Accept: application/json" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Test Card",
    "idList": "LIST_ID"
  }'

Environment Validation

System Requirements Check

# Node.js version (should be 18+)
node --version

# NPM version
npm --version

# TypeScript version (should be 5.7+)
npx tsc --version

# Check available memory
free -h  # Linux
vm_stat  # macOS

Dependency Verification

# Check installed dependencies
npm list

# Verify specific dependencies
npm list @modelcontextprotocol/sdk
npm list zod

# Check for dependency conflicts
npm audit

Environment-Specific Issues

macOS Issues

Issue: Permission Denied Errors

# Fix file permissions
chmod +x dist/index.js

# Fix directory permissions
chmod -R 755 /path/to/trello-desktop-mcp

# Check file ownership
ls -la dist/index.js

Issue: Path Resolution Problems

# Use full absolute paths
pwd  # Get current directory
/Users/username/Projects/trello-desktop-mcp

# Update config with full path
"/Users/username/Projects/trello-desktop-mcp/dist/index.js"

Windows Issues

Issue: Command Not Found

# Verify Node.js in PATH
where node

# Use full path to node if needed
"C:\\Program Files\\nodejs\\node.exe"

Issue: Path Separator Problems

// Use forward slashes or escaped backslashes
"args": ["C:/Projects/trello-desktop-mcp/dist/index.js"]
// OR
"args": ["C:\\Projects\\trello-desktop-mcp\\dist\\index.js"]

Linux Issues

Issue: Node.js Version Problems

# Install Node.js 18+ via package manager
# Ubuntu/Debian
curl -fsSL https://deb.nodesource.com/setup_18.x | sudo -E bash -
sudo apt-get install -y nodejs

# CentOS/RHEL/Fedora
curl -fsSL https://rpm.nodesource.com/setup_18.x | sudo bash -
sudo yum install -y nodejs

Getting Additional Help

Information to Collect

When reporting issues, include:

1. System Information

   # Operating system and version
   uname -a  # Linux/macOS
   ver       # Windows
   
   # Node.js version
   node --version
   
   # NPM version
   npm --version
   

2. Configuration

   // Sanitized version of your config (remove credentials)
   {
     "mcpServers": {
       "trello": {
         "command": "node",
         "args": ["/path/to/dist/index.js"],
         "env": {
           "TRELLO_API_KEY": "[REDACTED]",
           "TRELLO_TOKEN": "[REDACTED]"
         }
       }
     }
   }
   

3. Error Messages

   • Complete error text from Claude Desktop
   • Relevant log file entries
   • Steps to reproduce the issue

4. Build Information

   # Verify build status
   npm run type-check
   ls -la dist/
   

Community Support

• GitHub Issues: Report bugs and request features
• Documentation: Check other wiki pages for detailed information
• Claude Desktop Community: Claude Desktop user forums and communities

Professional Support

For production deployments:

• Review Deployment Guide for production considerations
• Consider Performance optimization techniques
• Implement Monitoring for proactive issue detection

---

Quick Resolution Flowchart:

1. Tools not appearing → Check path configuration and restart Claude Desktop
2. Authentication errors → Verify and regenerate Trello credentials
3. Rate limits → Wait 10 seconds and reduce request frequency
4. Network errors → Check internet connection and firewall settings
5. Performance issues → Use more specific requests and filtering
6. Still having issues → Enable debug logging and check log files