Troubleshooting

Having trouble with Pylee? This guide covers the most common issues and their solutions.

Quick Help: Most setup issues can be resolved by restarting your application completely and checking your API key. If problems persist, try the solutions below.

Common Issues and Solutions

Pylee MCP Server Not Appearing

Symptoms: Claude Desktop or other MCP clients don’t show Pylee as availableSolutions:

Verify Configuration File Location

Ensure your config file is in the correct location:

macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
Windows: %APPDATA%\Claude\claude_desktop_config.json
Linux: ~/.config/Claude/claude_desktop_config.json

Check JSON Syntax

Validate your JSON configuration:

{
  "mcpServers": {
    "pylee": {
      "command": "npx",
      "args": ["-y", "@pyleeai/pylee@latest"]
    }
  }
}

Restart Application

Completely quit and restart Claude Desktop (or your MCP client)

Check Node.js Installation

Verify Node.js is installed:

node --version
npm --version

Connection Timeout Issues

Symptoms: MCP server starts but times out when trying to connectSolutions:

Check Internet Connection

Ensure you have a stable internet connection

Verify Firewall Settings

Make sure your firewall isn’t blocking the connection:

Allow npx and node through your firewall
Check corporate firewall settings if applicable

Test Network Access

# Test connection to Pylee API
curl -I https://api.pyleeai.com/health

Try Alternative Configuration

If using npx fails, try installing globally:

npm install -g @pyleeai/mcp-server

Then update your config to use:

{
  "command": "pylee-mcp-server"
}

Permission Denied Errors

Symptoms: Errors about file permissions or access deniedSolutions:

Check File Permissions

Ensure you can read/write the configuration file:

# macOS/Linux
ls -la "~/Library/Application Support/Claude/"
# or
ls -la ~/.config/Claude/

Create Directory if Missing

# macOS
mkdir -p "~/Library/Application Support/Claude"

# Linux
mkdir -p ~/.config/Claude

Fix Ownership (macOS/Linux)

# macOS
sudo chown -R $(whoami) "~/Library/Application Support/Claude"

# Linux  
sudo chown -R $(whoami) ~/.config/Claude

Run as Administrator (Windows)

Try running your text editor as Administrator when editing the config file

Node.js or NPM Issues

Symptoms: Commands not found or version conflictsSolutions:

macOS
Windows
Linux

# Install Node.js via Homebrew
brew install node

# Or use Node Version Manager
curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.39.0/install.sh | bash
nvm install node
nvm use node

Download Node.js from nodejs.org
Run the installer as Administrator
Restart your command prompt/PowerShell
Verify installation:

node --version
npm --version

# Ubuntu/Debian
curl -fsSL https://deb.nodesource.com/setup_lts.x | sudo -E bash -
sudo apt-get install -y nodejs

# Fedora
sudo dnf install nodejs npm

# Arch Linux
sudo pacman -S nodejs npm

Registry Not Loading

Symptoms: Pylee connects but no registry servers are availableSolutions:

Check Registry Status

Log into Pylee Dashboard
Go to “Active Registries”
Verify your registries are activated

Refresh Registry

In your dashboard, click “Refresh” on your active registries

Check Permissions

Ensure you have access to the registries you’re trying to use

Test with Different Registry

Try activating a different registry to isolate the issue

Platform-Specific Issues

macOS
Windows
Linux
WSL

Common macOS Issues

Gatekeeper blocking execution:

# Allow npx to run
sudo spctl --master-disable
# Run your MCP client, then re-enable:
sudo spctl --master-enable

SIP (System Integrity Protection) issues:

Use Homebrew to install Node.js instead of the system installer
Avoid modifying system directories

Permission issues with Application Support:

# Fix permissions
sudo chown -R $(whoami) "~/Library/Application Support"

Common Windows Issues

Execution policy restrictions:

# Run PowerShell as Administrator
Set-ExecutionPolicy -ExecutionPolicy RemoteSigned -Scope CurrentUser

Path issues:

Add Node.js to your PATH environment variable
Restart command prompt after installing Node.js

AppData access issues:

Run text editor as Administrator
Check that %APPDATA% environment variable is set correctly

Common Linux Issues

Snap-installed applications:

Snap packages may have restricted file system access
Install Node.js via your package manager instead

Permission issues:

# Fix npm permissions
mkdir ~/.npm-global
npm config set prefix '~/.npm-global'
echo 'export PATH=~/.npm-global/bin:$PATH' >> ~/.bashrc
source ~/.bashrc

SELinux restrictions:

# Temporarily disable SELinux (if applicable)
sudo setenforce 0

Common WSL Issues

Mixed Windows/Linux paths:

Keep configuration files in Linux filesystem for better performance
Use Linux paths in your configuration

Node.js installation:

# Install via package manager, not Windows installer
curl -fsSL https://deb.nodesource.com/setup_lts.x | sudo -E bash -
sudo apt-get install -y nodejs

File system permissions:

# Ensure proper permissions
sudo chown -R $(whoami) ~/.config

Getting Debug Information

If you’re still having issues, gather this information before contacting support:

System Information

# Check versions
node --version
npm --version

# Check OS
uname -a  # macOS/Linux
# or
systeminfo  # Windows

Configuration File

Verify your configuration file exists and has correct content:

# macOS
cat "~/Library/Application Support/Claude/claude_desktop_config.json"

# Linux
cat ~/.config/Claude/claude_desktop_config.json

# Windows (PowerShell)
Get-Content "$env:APPDATA\Claude\claude_desktop_config.json"

Test MCP Server Directly

# Test if the MCP server starts
npx @pyleeai/pylee@latest

Check Network Connectivity

# Test API connectivity
curl -v https://api.pyleeai.com/health

Still Need Help?

Contact Support

Email us with your debug information

Community Discord

Get help from the community

GitHub Issues

Report bugs or request features

Documentation

Review the full documentation

When contacting support, please include:

Your operating system and version
Node.js and npm versions
Your configuration file (with API key redacted)
Any error messages you’re seeing
Steps you’ve already tried

Additional Resources

Getting Started Guide

Review the initial setup process

Registry Activation

Learn about managing MCP server registries

Configuration Guide

Advanced configuration options

Community Support

Connect with other Pylee users

Reporting Issues

If you can’t find a solution to your problem:

Check our GitHub Issues - Someone may have already reported the same issue
Search the documentation - Use the search function to find relevant information
Contact support - Include detailed information about your setup and the issue you’re experiencing

When reporting issues, please include your operating system, Node.js version, and any error messages you’re seeing. This helps us provide better support.

​Troubleshooting

​Common Issues and Solutions

​Platform-Specific Issues

​Common macOS Issues

​Common Windows Issues

​Common Linux Issues

​Common WSL Issues

​Getting Debug Information

​Still Need Help?

Contact Support

Community Discord

GitHub Issues

Documentation

​Additional Resources

Getting Started Guide

Registry Activation

Configuration Guide

Community Support

​Reporting Issues

Troubleshooting

Common Issues and Solutions

Platform-Specific Issues

Common macOS Issues

Common Windows Issues

Common Linux Issues

Common WSL Issues

Getting Debug Information

Still Need Help?

Additional Resources

Reporting Issues