# Troubleshooting Guide

This guide addresses common issues you might encounter when setting up and using the n8n MCP Server.

## Connection Issues

### Cannot Connect to n8n API

**Symptoms:** 
- Error messages mentioning "Connection refused" or "Cannot connect to n8n API"
- Timeout errors when trying to use MCP tools

**Possible Solutions:**
1. **Verify n8n is running:**
   - Ensure your n8n instance is running and accessible
   - Try accessing the n8n URL in a browser

2. **Check n8n API URL:**
   - Verify the `N8N_API_URL` in your `.env` file
   - Make sure it includes the full path (e.g., `http://localhost:5678/api/v1`)
   - Check for typos or incorrect protocol (http vs https)

3. **Network Configuration:**
   - If running on a different machine, ensure there are no firewall rules blocking access
   - Check if n8n is configured to allow remote connections

4. **HTTPS/SSL Issues:**
   - If using HTTPS, ensure certificates are valid
   - For self-signed certificates, you may need to set up additional configuration

### Authentication Failures

**Symptoms:**
- "Authentication failed" or "Invalid API key" messages
- 401 or 403 HTTP status codes

**Possible Solutions:**
1. **Verify API Key:**
   - Check that the `N8N_API_KEY` in your `.env` file matches the one in n8n
   - Create a new API key if necessary

2. **Check API Key Permissions:**
   - Ensure the API key has appropriate scopes/permissions
   - Required scopes: `workflow:read workflow:write workflow:execute`

3. **n8n API Settings:**
   - Verify that API access is enabled in n8n settings
   - Check if there are IP restrictions on API access

## MCP Server Issues

### Server Crashes or Exits Unexpectedly

**Symptoms:**
- The MCP server stops running unexpectedly
- Error messages in logs or console output

**Possible Solutions:**
1. **Check Node.js Version:**
   - Ensure you're using Node.js 18 or later
   - Check with `node --version`

2. **Check Environment Variables:**
   - Ensure all required environment variables are set
   - Verify the format of the environment variables

3. **View Debug Logs:**
   - Set `DEBUG=true` in your `.env` file
   - Check the console output for detailed error messages

4. **Memory Issues:**
   - If running on a system with limited memory, increase available memory
   - Check for memory leaks or high consumption patterns

### AI Assistant Cannot Communicate with MCP Server

**Symptoms:**
- AI assistant reports it cannot connect to the MCP server
- Tools are not available in the assistant interface

**Possible Solutions:**
1. **Verify Server Registration:**
   - Ensure the server is properly registered with your AI assistant platform
   - Check the configuration settings for the MCP server in your assistant

2. **Server Running Check:**
   - Verify the MCP server is running
   - Check that it was started with the correct environment

3. **Restart Components:**
   - Restart the MCP server
   - Refresh the AI assistant interface
   - If using a managed AI assistant, check platform status

## Tool-Specific Issues

### Workflow Operations Fail

**Symptoms:**
- Cannot list, create, or update workflows
- Error messages about missing permissions

**Possible Solutions:**
1. **API Key Scope:**
   - Ensure your API key has `workflow:read` and `workflow:write` permissions
   - Create a new key with appropriate permissions if needed

2. **n8n Version:**
   - Check if your n8n version supports all the API endpoints being used
   - Update n8n to the latest version if possible

3. **Workflow Complexity:**
   - Complex workflows with custom nodes may not work correctly
   - Try with simpler workflows to isolate the issue

### Execution Operations Fail

**Symptoms:**
- Cannot execute workflows or retrieve execution data
- Execution starts but fails to complete

**Possible Solutions:**
1. **API Key Scope:**
   - Ensure your API key has the `workflow:execute` permission
   - Create a new key with appropriate permissions if needed

2. **Workflow Status:**
   - Check if the target workflow is active
   - Verify the workflow executes correctly in the n8n interface

3. **Workflow Inputs:**
   - Ensure all required inputs for workflow execution are provided
   - Check the format of input data

## Getting More Help

If you're still experiencing issues after trying these troubleshooting steps:

1. **Check GitHub Issues:**
   - Look for similar issues in the [GitHub repository](https://github.com/yourusername/n8n-mcp-server/issues)
   - Create a new issue with detailed information about your problem

2. **Submit Logs:**
   - Enable debug logging with `DEBUG=true`
   - Include relevant logs when seeking help

3. **Community Support:**
   - Ask in the n8n community forums
   - Check MCP-related discussion groups