🔧 Troubleshooting Guide¶

Solve common EasyPanel MCP issues.

🔍 Diagnostic Steps¶

1. Check Server Status¶

# Test configuration
python -c "from config import config; print(config.easypanel.base_url)"

# Test EasyPanel connection
python -c "
import asyncio
from src.client import EasyPanelClient
from config import config

async def test():
    client = EasyPanelClient(config.easypanel)
    await client.connect()
    healthy = await client.health_check()
    print(f'EasyPanel healthy: {healthy}')
    await client.disconnect()

asyncio.run(test())
"

2. Check Logs¶

Run server with debug logging:

MCP_LOG_LEVEL=DEBUG python src/server.py

❌ Common Errors¶

Connection Refused¶

ConnectionRefusedError: [Errno 111] Connection refused

Cause: EasyPanel not reachable

Solutions: 1. Verify EasyPanel is running 2. Check URL includes protocol: https:// 3. Test connectivity: curl https://your-easypanel.com 4. Check firewall rules

Unauthorized¶

HTTP 401 Unauthorized

Cause: Invalid API key

Solutions: 1. Regenerate API key in EasyPanel 2. Update .env with new key 3. Check for typos in key 4. Ensure no extra spaces

Timeout¶

TimeoutError" or "ReadTimeout

Cause: Request taking too long

Solutions: 1. Increase timeout in .env:

EASYPANEL_TIMEOUT=120

2. Check network latency 3. Verify EasyPanel performance 4. Reduce request complexity

Port in Use¶

OSError: [Errno 48] Address already in use

Cause: Port 8080 already bound

Solutions: 1. Change port in .env:

MCP_PORT=8081

2. Find process using port:

# Windows
netstat -ano | findstr :8080

# macOS/Linux
lsof -i :8080

3. Kill conflicting process

Module Not Found¶

ModuleNotFoundError: No module named 'httpx'

Cause: Dependencies not installed

Solutions: 1. Activate virtual environment 2. Reinstall dependencies:

pip install -r requirements.txt --force-reinstall

3. Verify installation:

python -c "import httpx; print(httpx.__version__)"

Python Version Error¶

SyntaxError" or "TypeError

Cause: Python version < 3.10

Solutions: 1. Check version: python --version 2. Upgrade Python to 3.10+ 3. Use version manager (pyenv, nvm)

🤖 AI Agent Issues¶

Claude Can't Connect¶

MCP server not available

Solutions: 1. Verify absolute path in config 2. Test server manually first 3. Check Python path in config 4. Restart Claude Desktop 5. Check Claude logs

Config example:

{
  "mcpServers": {
    "easypanel": {
      "command": "/usr/bin/python3",
      "args": ["/absolute/path/to/server.py"],
      "env": {
        "EASYPANEL_URL": "https://panel.com",
        "EASYPANEL_API_KEY": "key"
      }
    }
  }
}

n8n Connection Fails¶

ECONNREFUSED

Solutions: 1. Start MCP in HTTP mode: python src/server.py http 2. Check n8n can reach MCP server 3. Use correct URL in HTTP Request node 4. Check firewall between n8n and MCP

GitHub Actions Fails¶

HTTP request failed

Solutions: 1. Ensure MCP server is publicly accessible 2. Verify secrets are set correctly 3. Test curl command locally 4. Check GitHub Actions logs

🌐 Network Issues¶

Services Can't Communicate¶

Connection timeout between services

Solutions: 1. Verify services on same network 2. Check service names used as hostnames 3. Test network connectivity:

docker network ls
docker network inspect network-name

4. Ensure internal networks are truly isolated

Can't Access Service¶

Service not reachable from internet

Solutions: 1. Check ports are mapped: "ports": ["8080:8080"] 2. Verify service is running 3. Check firewall rules 4. Test locally: curl http://localhost:8080

🐛 Debug Mode¶

Enable Verbose Logging¶

# In .env
MCP_DEBUG=true
MCP_LOG_LEVEL=DEBUG

View Server Logs¶

# Run and save logs
python src/server.py 2>&1 | tee mcp.log

Debug EasyPanel API¶

# Test API directly
import httpx
import asyncio

async def debug():
    async with httpx.AsyncClient() as client:
        response = await client.get(
            "https://your-easypanel.com/api/health",
            headers={"Authorization": "Bearer YOUR_KEY"}
        )
        print(f"Status: {response.status_code}")
        print(f"Body: {response.json()}")

asyncio.run(debug())

📊 Performance Issues¶

Slow Deployments¶

Causes: - Network latency - EasyPanel overloaded - Large Docker images

Solutions: 1. Increase timeout 2. Optimize Docker images (smaller) 3. Check EasyPanel resources 4. Use local Docker registry

High Memory Usage¶

Solutions: 1. Set resource limits:

"resources": {
  "memory": "512M"
}

2. Monitor with get_service 3. Scale down unused services

🆘 Getting Help¶

1. Check Documentation¶

2. Enable Debug Mode¶

MCP_DEBUG=true python src/server.py

3. Gather Information¶

Collect: - Error messages (full text) - Server logs - Configuration (without secrets) - Steps to reproduce

4. Open GitHub Issue¶

Visit: github.com/dannymaaz/easypanel-mcp/issues

Include: - Description of issue - Error messages - Configuration - Expected behavior - Actual behavior

✅ Health Check Checklist¶

Run through this checklist when debugging:

Still stuck? Open an issue on GitHub