TROUBLESHOOTING.md•9.02 kB
# 🔧 Troubleshooting Guide
Common issues and their solutions for MCP Energy Server.
## Table of Contents
1. [Installation Issues](#installation-issues)
2. [Server Won't Start](#server-wont-start)
3. [Claude Desktop Connection](#claude-desktop-connection)
4. [API Errors](#api-errors)
5. [GitHub Issues](#github-issues)
6. [Performance Issues](#performance-issues)
---
## Installation Issues
### ❌ "pip: command not found"
**Problem**: pip is not installed or not in PATH
**Solutions**:
```bash
# Try pip3 instead
pip3 install -e .
# Or use python -m pip
python -m pip install -e .
# On Ubuntu/Debian
sudo apt-get install python3-pip
# On macOS with Homebrew
brew install python3
```
### ❌ "Python version not supported"
**Problem**: Python version is below 3.10
**Solution**:
```bash
# Check version
python --version
# Install Python 3.10+ from python.org
# Or use pyenv
pyenv install 3.11
pyenv global 3.11
```
### ❌ "ModuleNotFoundError: No module named 'mcp'"
**Problem**: Dependencies not installed
**Solution**:
```bash
# Reinstall dependencies
pip install -e . --force-reinstall
# Or install from requirements.txt
pip install -r requirements.txt
# Update pip first
pip install --upgrade pip
```
---
## Server Won't Start
### ❌ "Address already in use"
**Problem**: Another process is using the port
**Solution**:
```bash
# Find and kill the process (macOS/Linux)
lsof -ti:8080 | xargs kill -9
# Windows
netstat -ano | findstr :8080
taskkill /PID <PID> /F
```
### ❌ "ImportError: cannot import name 'Server'"
**Problem**: MCP library not installed correctly
**Solution**:
```bash
# Reinstall MCP
pip uninstall mcp
pip install mcp>=0.9.0
# Check installation
python -c "import mcp; print(mcp.__version__)"
```
### ❌ Server starts then immediately stops
**Problem**: Error in server.py or configuration
**Solution**:
```bash
# Run with verbose output
python -v server.py
# Check for syntax errors
python -m py_compile server.py
# Check logs
# Add this to server.py if needed:
import logging
logging.basicConfig(level=logging.DEBUG)
```
### ❌ "SyntaxError: invalid syntax"
**Problem**: Code incompatibility with Python version
**Solution**:
- Ensure you're using Python 3.10+
- Check for tabs vs spaces
- Verify file encoding is UTF-8
---
## Claude Desktop Connection
### ❌ No 🔌 icon in Claude Desktop
**Problem**: Server not connecting to Claude
**Solutions**:
1. **Check config file location**:
```bash
# macOS
cat ~/Library/Application\ Support/Claude/claude_desktop_config.json
# Windows
type %APPDATA%\Claude\claude_desktop_config.json
```
2. **Verify JSON syntax**:
```bash
# Use a JSON validator
python -m json.tool < claude_desktop_config.json
```
3. **Check path is absolute**:
```json
{
"mcpServers": {
"energy": {
"command": "python",
"args": ["-m", "server"],
"cwd": "/full/absolute/path/to/mcp-energy"
}
}
}
```
4. **Restart Claude Desktop completely**:
- Quit Claude Desktop (not just close window)
- Wait 5 seconds
- Reopen Claude Desktop
### ❌ "Error: spawn python ENOENT"
**Problem**: Python not found in PATH
**Solutions**:
```json
// Option 1: Use full Python path
{
"mcpServers": {
"energy": {
"command": "/usr/local/bin/python3",
"args": ["-m", "server"],
"cwd": "/path/to/mcp-energy"
}
}
}
// Option 2: Use virtual environment Python
{
"mcpServers": {
"energy": {
"command": "/path/to/mcp-energy/venv/bin/python",
"args": ["-m", "server"],
"cwd": "/path/to/mcp-energy"
}
}
}
```
### ❌ Server connects but tools don't work
**Problem**: Server running but tools unavailable
**Solution**:
```bash
# Test server directly
python server.py
# Then try sending a test message
# Check server logs
# Add logging to server.py
# Verify API key
python -c "from server import EIA_API_KEY; print(EIA_API_KEY)"
```
---
## API Errors
### ❌ "401 Unauthorized"
**Problem**: Invalid or missing API key
**Solution**:
1. Check your API key is correct
2. Get a new key from https://www.eia.gov/opendata/register.php
3. Update `.env` file:
```bash
echo "EIA_API_KEY=your_new_key_here" > .env
```
### ❌ "429 Too Many Requests"
**Problem**: Rate limit exceeded
**Solution**:
- Wait before making more requests
- Implement caching in your application
- Consider upgrading your API plan
### ❌ "503 Service Unavailable"
**Problem**: EIA API is down
**Solution**:
- Check EIA status: https://www.eia.gov/opendata/
- Wait and retry
- Implement retry logic with backoff
### ❌ "Network timeout"
**Problem**: Request took too long
**Solution**:
```python
# Increase timeout in server.py
async with httpx.AsyncClient(timeout=60.0) as client: # Increase from 30.0
# ... rest of code
```
---
## GitHub Issues
### ❌ "Permission denied (publickey)"
**Problem**: SSH key not configured
**Solutions**:
```bash
# Use HTTPS instead
git remote set-url origin https://github.com/USERNAME/mcp-energy.git
# Or setup SSH key
ssh-keygen -t ed25519 -C "your_email@example.com"
cat ~/.ssh/id_ed25519.pub # Add to GitHub settings
```
### ❌ "Push rejected"
**Problem**: Remote has changes you don't have
**Solution**:
```bash
# Pull first
git pull origin main --rebase
# Then push
git push origin main
```
### ❌ "Large file detected"
**Problem**: File too large for GitHub
**Solution**:
```bash
# Remove large files
git rm --cached large_file.csv
# Add to .gitignore
echo "*.csv" >> .gitignore
echo "*.db" >> .gitignore
# Commit changes
git commit -m "Remove large files"
```
---
## Performance Issues
### ❌ Server is slow
**Problem**: Network or API delays
**Solutions**:
1. **Implement caching**:
```python
from functools import lru_cache
@lru_cache(maxsize=100)
async def fetch_eia_data_cached(route: str, params_str: str):
# ... implementation
```
2. **Reduce data size**:
```python
params = {
"length": 10, # Instead of 100
# ...
}
```
3. **Use connection pooling**:
```python
# Reuse client
client = httpx.AsyncClient(timeout=30.0)
# Use same client for multiple requests
```
### ❌ High memory usage
**Problem**: Large responses consuming memory
**Solutions**:
- Limit response size
- Process data in chunks
- Clear cache regularly
- Use generators instead of lists
---
## Debug Mode
Enable debug logging:
```python
# Add to top of server.py
import logging
logging.basicConfig(
level=logging.DEBUG,
format='%(asctime)s - %(name)s - %(levelname)s - %(message)s'
)
logger = logging.getLogger(__name__)
# Use throughout code
logger.debug("Fetching data from %s", route)
logger.error("API error: %s", str(e))
```
---
## Testing Connection
### Test 1: Server Starts
```bash
python server.py
# Should not exit immediately
# Press Ctrl+C to stop
```
### Test 2: Dependencies
```bash
python -c "import mcp; import httpx; print('OK')"
# Should print "OK"
```
### Test 3: API Access
```bash
python -c "
from server import EIA_API_KEY
import httpx
import asyncio
async def test():
async with httpx.AsyncClient() as client:
r = await client.get(
'https://api.eia.gov/v2/electricity/retail-sales/data',
params={'api_key': EIA_API_KEY, 'length': 1}
)
print(r.status_code)
asyncio.run(test())
"
# Should print "200"
```
### Test 4: Claude Config
```bash
# Validate JSON
python -m json.tool claude_desktop_config.json
# Should print formatted JSON with no errors
```
---
## Getting Help
If you're still stuck:
1. **Check logs**:
- Claude Desktop: Developer Tools Console
- Server: Add logging to server.py
2. **Create minimal test**:
```python
# test_minimal.py
import asyncio
from server import fetch_eia_data
async def test():
result = await fetch_eia_data(
"electricity/retail-sales/data",
{"api_key": "YOUR_KEY", "length": 1}
)
print(result)
asyncio.run(test())
```
3. **Check versions**:
```bash
python --version
pip list | grep mcp
pip list | grep httpx
```
4. **Create GitHub issue**:
Include:
- Error message
- Python version
- Operating system
- Steps to reproduce
5. **Resources**:
- MCP Docs: https://modelcontextprotocol.io
- EIA API: https://www.eia.gov/opendata/
- Python asyncio: https://docs.python.org/3/library/asyncio.html
---
## Quick Fix Commands
```bash
# Nuclear option: Fresh start
rm -rf venv/
python3 -m venv venv
source venv/bin/activate # or venv\Scripts\activate.bat on Windows
pip install -e . --force-reinstall
# Verify installation
python -c "import mcp, httpx; print('Dependencies OK')"
python -m py_compile server.py && echo "Syntax OK"
python server.py &
sleep 2
pkill -f "python server.py"
echo "Server test complete"
```
---
Remember: Most issues are configuration-related. Double-check paths, Python versions, and JSON syntax!