Skip to main content

​
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

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

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
2

Check JSON Syntax

Validate your JSON configuration:
{
  "mcpServers": {
    "pylee": {
      "command": "npx",
      "args": ["-y", "@pyleeai/pylee@latest"]
    }
  }
}
3

Restart Application

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

Check Node.js Installation

Verify Node.js is installed:
node --version
npm --version
Symptoms: MCP server starts but times out when trying to connectSolutions:
1

Check Internet Connection

Ensure you have a stable internet connection
2

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
3

Test Network Access

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

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"
}
Symptoms: Errors about file permissions or access deniedSolutions:
1

Check File Permissions

Ensure you can read/write the configuration file:
# macOS/Linux
ls -la "~/Library/Application Support/Claude/"
# or
ls -la ~/.config/Claude/
2

Create Directory if Missing

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

# Linux
mkdir -p ~/.config/Claude
3

Fix Ownership (macOS/Linux)

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

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

Run as Administrator (Windows)

Try running your text editor as Administrator when editing the config file
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
Symptoms: Pylee connects but no registry servers are availableSolutions:
1

Check Registry Status

  1. Log into Pylee Dashboard
  2. Go to “Active Registries”
  3. Verify your registries are activated
2

Refresh Registry

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

Check Permissions

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

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"

​
Getting Debug Information

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

System Information

# Check versions
node --version
npm --version

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

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"
3

Test MCP Server Directly

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

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:
  1. Check our GitHub Issues - Someone may have already reported the same issue
  2. Search the documentation - Use the search function to find relevant information
  3. 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.
⌘I