Planka MCP Server

# ⚠️ Troubleshooting This page provides solutions to common issues you might encounter when setting up or using Kanban MCP. ## 🔌 Connection Issues ### 🚫 MCP Server Cannot Connect to Planka **Symptoms:** - Error messages about connection refused - Timeout errors when trying to access Planka API - Errors like `Error: connect ECONNREFUSED` **Possible Solutions:** 1. **🔍 Check if Planka is running:** ```bash docker ps | grep planka ``` If Planka is not listed, restart it with `npm run up` 2. **🌐 Verify network configuration:** - When running MCP in Docker, use `host.docker.internal` instead of `localhost` in the `PLANKA_BASE_URL` - Ensure the port in `PLANKA_BASE_URL` matches the port Planka is running on (default: 3333) - For macOS and Windows, `host.docker.internal` resolves to the host machine - For Linux, you may need to use `--add-host=host.docker.internal:host-gateway` when running Docker 3. **🔄 Check Docker network:** ```bash docker network ls docker network inspect kanban-mcp_default ``` Ensure the Planka container is properly connected to the network 4. **📝 Verify environment variables:** - Double-check the values for `PLANKA_BASE_URL` in your Docker command - Ensure environment variables are set with explicit values, not variable references ```bash # ❌ Don't use variable references -e PLANKA_BASE_URL=http://host.docker.internal:${PLANKA_PORT} # ✅ Use explicit values -e PLANKA_BASE_URL=http://host.docker.internal:3333 ``` ### 🔑 Authentication Failures **Symptoms:** - "Invalid credentials" errors - "Unauthorized" errors when MCP tries to access Planka - Error messages like `Error: Request failed with status code 401` **Possible Solutions:** 1. **👤 Verify agent credentials:** - Double-check that the email and password in your MCP configuration match the agent user created in Planka - Try logging into Planka manually with the agent credentials to verify they work - Ensure both email and password are correctly specified in environment variables 2. **🔄 Reset agent password:** - Log in to Planka as admin - Go to user management - Reset the agent user's password - Update the password in your MCP configuration 3. **🔣 Check for special characters:** - If your password contains special characters, ensure they are properly escaped in your configuration - Consider using a simpler password for testing purposes ## 🐳 Docker Issues ### 🏗️ Docker Image Build Failures **Symptoms:** - Errors during `npm run build-docker` - Missing dependencies or build errors **Possible Solutions:** 1. **🧹 Clean and rebuild:** ```bash # Remove existing images docker rmi mcp-planka:latest # Clean npm cache and node_modules npm cache clean --force rm -rf node_modules # Reinstall dependencies and rebuild npm install npm run build-docker ``` 2. **💾 Check Docker disk space:** ```bash docker system df ``` If disk space is low, clean up unused Docker resources: ```bash docker system prune -a ``` ### 🚀 Container Startup Issues **Symptoms:** - Container exits immediately after starting - Error logs showing startup failures **Possible Solutions:** 1. **📜 Check container logs:** ```bash docker logs $(docker ps -a | grep mcp-planka | awk '{print $1}') ``` 2. **🔍 Run in interactive mode for debugging:** ```bash docker run -it --rm mcp-planka:latest /bin/sh ``` This will give you a shell inside the container to investigate issues 3. **🔗 Test network connectivity from inside the container:** ```bash docker run -it --rm mcp-planka:latest /bin/sh # Inside the container ping host.docker.internal curl http://host.docker.internal:3333 ``` This can help verify if the container can reach your host machine ## 📊 Planka Issues ### 🗄️ Database Connection Errors **Symptoms:** - Planka fails to start - Logs show database connection errors **Possible Solutions:** 1. **🔍 Check PostgreSQL container:** ```bash docker ps | grep postgres ``` If not running, check logs: ```bash docker logs $(docker ps -a | grep postgres | awk '{print $1}') ``` 2. **🔄 Reset PostgreSQL data:** ```bash # Stop containers npm run down # Remove PostgreSQL volume docker volume rm kanban-mcp_postgres-data # Start containers again npm run up ``` Note: This will delete all Planka data! ### 🖥️ UI Issues **Symptoms:** - Planka UI not loading properly - JavaScript errors in browser console **Possible Solutions:** 1. **🧹 Clear browser cache:** - Press Ctrl+Shift+Delete in your browser - Select cache and cookies - Clear data 2. **🌐 Try a different browser:** - Some browsers may have compatibility issues with Planka ## 🤖 MCP Integration Issues ### 🔄 Claude Cannot Access Kanban Tools **Symptoms:** - Claude doesn't recognize kanban commands - Error messages about MCP server not being available **Possible Solutions:** 1. **⚙️ Verify MCP configuration:** - Check that the MCP server is properly configured in Cursor settings - Ensure the Docker command is correct with proper environment variables 2. **🔄 Restart Cursor:** - Sometimes a full restart of Cursor is needed after MCP configuration changes 3. **📜 Check MCP logs:** - Look for error messages in the Cursor MCP logs - Verify that the MCP server is connecting to Planka successfully ### 🔒 Project Access Issues **Symptoms:** - Claude can connect to MCP but cannot see projects - "Access denied" errors when trying to manage cards - Error messages like `Error: Request failed with status code 403` **Possible Solutions:** 1. **👥 Check agent permissions:** - Ensure the agent user has been added to the project as a manager - Verify the agent has the necessary permissions in Planka 2. **🔢 Project ID issues:** - Make sure you're using the correct project ID - List all available projects to confirm the project exists and is accessible ## 🛑 Common Error Messages and Solutions ### "Error: connect ECONNREFUSED" This indicates that the MCP server cannot connect to Planka. **Solution:** - Ensure Planka is running - Check the URL and port in `PLANKA_BASE_URL` - Use `host.docker.internal` instead of `localhost` when running in Docker - Verify the port is correct and not blocked by a firewall ### "Error: Request failed with status code 401" This indicates authentication issues. **Solution:** - Verify agent credentials (both email and password) - Check if the agent user exists in Planka - Reset the agent password if necessary - Ensure credentials are properly passed as environment variables ### "Error: Request failed with status code 403" This indicates permission issues. **Solution:** - Ensure the agent user has been added to the project - Check that the agent has manager permissions - Verify the agent has access to the specific board/list you're trying to access ## 📞 Getting Additional Help If you're still experiencing issues after trying these troubleshooting steps: 1. **🔍 Check GitHub Issues:** - Visit the [Kanban MCP GitHub repository](https://github.com/bradrisse/kanban-mcp/issues) - Search for similar issues or create a new one 2. **📊 Gather Diagnostic Information:** ```bash # Get Docker container status docker ps -a # Get Docker logs docker logs $(docker ps -a | grep mcp-planka | awk '{print $1}') docker logs $(docker ps -a | grep planka | awk '{print $1}') # Get Docker network information docker network inspect planka-mcp_default ``` 3. **📝 Include Relevant Information When Seeking Help:** - Error messages - Steps to reproduce the issue - Environment details (OS, Docker version, etc.) - Configuration (with sensitive information redacted)