# Tello Drone MCP Server - Mac Setup Guide

## Prerequisites

1. **Python 3.10 or higher** - Check your version:
   ```bash
   python3 --version
   ```

2. **Homebrew** (optional, but recommended for installing Python if needed):
   ```bash
   /bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"
   ```

## Step-by-Step Setup

### 1. Create Project Directory
```bash
mkdir ~/tello-mcp
cd ~/tello-mcp
```

### 2. Create a Virtual Environment (Recommended)
```bash
python3.12 -m venv venv
source venv/bin/activate
```

### 3. Install Dependencies
```bash
pip install mcp djitellopy opencv-python
```

### 4. Make the Server Script executable

```bash
chmod +x tello_server.py
```

### 5. Test the Server (Optional)
Before configuring Claude, you can test that everything works:

```bash
# Make sure you're in the virtual environment
source ~/tello-mcp/venv/bin/activate

# Turn on your Tello and connect to its WiFi first!

# Run the server
python tello_server.py
```

Press `Ctrl+C` to stop when done testing.

## Configure Claude Desktop

### Location of claude_desktop_config.json on Mac

The config file is located at:
```
~/Library/Application Support/Claude/claude_desktop_config.json
```

### Open the Config File

**Option 1: Using Terminal**
```bash
# Create the directory if it doesn't exist
mkdir -p ~/Library/Application\ Support/Claude

# Open in your default text editor
open ~/Library/Application\ Support/Claude/claude_desktop_config.json
```

**Option 2: Using Finder**
1. Open Finder
2. Press `Cmd + Shift + G` (Go to Folder)
3. Paste: `~/Library/Application Support/Claude`
4. Open `claude_desktop_config.json` with TextEdit or VS Code

**Option 3: Using nano (command line editor)**
```bash
nano ~/Library/Application\ Support/Claude/claude_desktop_config.json
```

### Add the Configuration

If the file is empty or doesn't exist, add this:

```json
{
  "mcpServers": {
    "tello-drone": {
      "command": "/Users/YOUR_USERNAME/tello-mcp/venv/bin/python",
      "args": [
        "/Users/YOUR_USERNAME/tello-mcp/tello_server.py"
      ]
    }
  }
}
```

**Replace `YOUR_USERNAME`** with your actual Mac username!

### Find Your Username

If you're not sure of your username:
```bash
echo $USER
```

Or use the `~` shortcut (though absolute paths are more reliable):
```bash
# Get the full path
echo ~/tello-mcp/venv/bin/python
echo ~/tello-mcp/tello_server.py
```

### Alternative: Using System Python

If you prefer not to use a virtual environment:

```json
{
  "mcpServers": {
    "tello-drone": {
      "command": "python3",
      "args": [
        "/Users/YOUR_USERNAME/tello-mcp/tello_server.py"
      ]
    }
  }
}
```

## Using the Tello with Claude

### 1. Connect to Tello WiFi
- Turn on your Tello drone
- Go to Mac WiFi settings
- Connect to the Tello network (usually named `TELLO-XXXXXX`)

### 2. Restart Claude Desktop
Quit and restart Claude Desktop for the configuration to take effect.

### 3. Start Flying!
Try these commands in Claude:
- "Connect to my Tello drone"
- "What's the battery level?"
- "Take off"
- "Move forward 50 centimeters"
- "Take a photo"
- "Land"

## Troubleshooting

### "Command not found" error
- Make sure the paths in the config are absolute (start with `/Users/`)
- Verify the Python path: `which python3`
- Check that tello_server.py exists: `ls ~/tello-mcp/tello_server.py`

### "Module not found" error
- Activate your virtual environment: `source ~/tello-mcp/venv/bin/activate`
- Reinstall dependencies: `pip install mcp djitellopy opencv-python`
- Make sure you're using the venv Python in the config

### Can't connect to drone
- Verify you're connected to Tello WiFi
- Check the drone is powered on and the lights are blinking
- Try pinging the drone: `ping 192.168.10.1`

### Photos not saving
The photos will save to the directory where you run Claude from. To specify a location, modify the `take_photo` function in `tello_server.py` to use an absolute path:

```python
filename = arguments.get("filename", "/Users/YOUR_USERNAME/tello-mcp/photos/tello_photo.jpg")
```

## Quick Reference

**Activate virtual environment:**
```bash
source ~/tello-mcp/venv/bin/activate
```

**Deactivate virtual environment:**
```bash
deactivate
```

**View Claude logs (if there are issues):**
```bash
tail -f ~/Library/Logs/Claude/mcp*.log
```

**Config file location:**
```
~/Library/Application Support/Claude/claude_desktop_config.json
```

## Debug

The Tello sends two types of communication:

Command responses (working ?) - on UDP port 8889
State data stream (working ?) - on UDP port 8890


# Find what's using a port, for example 8889:

```
lsof -i :8889

# You'll see output like:
# COMMAND   PID   USER   FD   TYPE     DEVICE SIZE/OFF NODE NAME
# Python    1234  linsun 3u   IPv4    0x...      0t0  UDP *:8889

# Kill that process (replace 1234 with the actual PID)
kill -9 1234
```

If 8889 works but 8890 doesn't, macOS might be blocking UDP port 8890.

## Safety Reminders

- Always fly in an open area away from people and obstacles
- Keep the drone in visual line of sight
- Monitor battery levels (don't fly below 20%)
- Have a clear landing area
- The emergency stop cuts motors immediately - use only in real emergencies

Happy flying! 🚁