# Futurama Quote Machine MCP Server

A simple connector that lets you interact with Futurama quotes directly through Claude Desktop! No need to switch between apps - just ask Claude to find quotes, add new ones, or manage your collection.

## What This Does

This tool connects Claude Desktop to the [Futurama Quote Machine API](https://fqm.jeremyschroeder.net/api/), giving you these superpowers:

- 🎲 **Get random quotes** - "Give me a random Futurama quote"
- 🔍 **Search quotes** - "Find quotes from Bender about robots"
- 📝 **Add new quotes** - "Add this quote: 'Shut up and take my money!' by Fry"
- ✏️ **Edit quotes** - "Update quote 123 to fix that typo"
- 🗑️ **Delete quotes** - "Remove quote 456"
- 👥 **List characters** - "What characters have quotes?"

## Quick Start (5 Minutes)

### Step 1: Download This Project

**Option A: Download ZIP**
1. Click the green "Code" button above
2. Click "Download ZIP"
3. Unzip to your Desktop

**Option B: Clone with Git**
```bash
git clone https://github.com/BitsofJeremy/futurama-quote-machine-mcp.git
cd futurama-quote-machine-mcp
```

### Step 2: Set Up Python

**On Mac:**
```bash
# Install Python if you don't have it (using Homebrew)
/bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"
brew install python

# Create virtual environment
python3 -m venv venv
source venv/bin/activate

# Install requirements
pip install mcp httpx
```

**On Windows:**
```bash
# Download Python from python.org if you don't have it

# Create virtual environment
python -m venv venv
venv\Scripts\activate

# Install requirements
pip install mcp httpx
```

### Step 3: Configure Claude Desktop

**On Mac:**
```bash
# Copy the configuration file
mkdir -p ~/Library/Application\ Support/Claude
cp claude_desktop_config.json ~/Library/Application\ Support/Claude/claude_desktop_config.json
```

**On Windows:**
```bash
# Copy the configuration file
mkdir %APPDATA%\Claude
copy claude_desktop_config.json %APPDATA%\Claude\claude_desktop_config.json
```

### Step 4: Update the Configuration

Edit the config file you just copied and change the path to match where you put this project:

```json
{
  "mcpServers": {
    "futurama-quote-machine": {
      "command": "/PATH/TO/YOUR/PROJECT/run_server.sh",
      "args": [],
      "env": {}
    }
  }
}
```

**Replace `/PATH/TO/YOUR/PROJECT/` with your actual path, like:**
- Mac: `/Users/yourname/Desktop/futurama-quote-machine-mcp/run_server.sh`
- Windows: `C:\Users\YourName\Desktop\futurama-quote-machine-mcp\run_server.bat`

### Step 5: Start Using It!

1. **Restart Claude Desktop** (important!)
2. **Try these commands:**
   - "Get me a random Futurama quote"
   - "Show me quotes from Professor Farnsworth"
   - "What characters have quotes?"
   - "Add a new quote: 'Bite my shiny metal ass!' by Bender"

## Detailed Installation Guide

### Prerequisites

- **Python 3.8 or newer** - [Download here](https://www.python.org/downloads/)
- **Claude Desktop app** - [Download here](https://claude.ai/download)
- **Internet connection** (to fetch quotes from the API)

### Installation Steps

1. **Check if Python is installed:**
   ```bash
   python --version
   # or try:
   python3 --version
   ```
   You should see something like "Python 3.9.7" or newer.

2. **Download this project:**
   - Download the ZIP file and extract it, OR
   - Use `git clone` if you know Git

3. **Open Terminal/Command Prompt:**
   - **Mac:** Press Cmd+Space, type "Terminal"
   - **Windows:** Press Win+R, type "cmd"

4. **Navigate to the project folder:**
   ```bash
   cd /path/to/futurama-quote-machine-mcp
   ```

5. **Create a virtual environment:**
   ```bash
   # Mac/Linux:
   python3 -m venv venv
   source venv/bin/activate
   
   # Windows:
   python -m venv venv
   venv\Scripts\activate
   ```

6. **Install required packages:**
   ```bash
   pip install mcp httpx
   ```

7. **Make the script executable (Mac/Linux only):**
   ```bash
   chmod +x run_server.sh
   ```

8. **Test the server:**
   ```bash
   # Mac/Linux:
   ./run_server.sh
   
   # Windows:
   run_server.bat
   ```
   If it works, you'll see no errors and it will wait for connections.

9. **Configure Claude Desktop:**
   
   Find your Claude Desktop configuration file:
   - **Mac:** `~/Library/Application Support/Claude/claude_desktop_config.json`
   - **Windows:** `%APPDATA%\Claude\claude_desktop_config.json`

   If the file doesn't exist, create it. Add this content (update the path):

   ```json
   {
     "mcpServers": {
       "futurama-quote-machine": {
         "command": "/FULL/PATH/TO/YOUR/PROJECT/run_server.sh",
         "args": [],
         "env": {}
       }
     }
   }
   ```

10. **Restart Claude Desktop** and test!

## Usage Examples

Once everything is set up, you can chat naturally with Claude:

### Getting Quotes
- "Give me a random Futurama quote"
- "Show me 5 quotes from Bender"
- "Find quotes about robots"
- "What did Professor Farnsworth say about science?"

### Managing Quotes
- "Add this quote: 'Woo! Go team!' by Bender"
- "Update quote 42 to say 'Good news, everyone!' by Professor Farnsworth"
- "Delete quote 123"

### Exploring the Database
- "How many quotes are there total?"
- "What characters have quotes?"
- "Show me page 2 of quotes"

## Troubleshooting

### "Server not found" or "Connection failed"

1. **Check the path in your config file** - Make sure it points to where you actually put the project
2. **Restart Claude Desktop** after any config changes
3. **Test the server manually** by running `./run_server.sh` in Terminal

### "Python not found" errors

1. **Install Python** from [python.org](https://python.org)
2. **Make sure it's in your PATH** - try `python3` instead of `python`

### "Permission denied" (Mac/Linux)

```bash
chmod +x run_server.sh
```

### "Module not found" errors

Make sure you activated the virtual environment and installed the packages:
```bash
source venv/bin/activate  # Mac/Linux
# or
venv\Scripts\activate     # Windows

pip install mcp httpx
```

### Still having issues?

1. **Check the Claude Desktop logs** - Look for error messages when the server starts
2. **Test the API directly** - Visit [https://fqm.jeremyschroeder.net/api/](https://fqm.jeremyschroeder.net/api/) in your browser
3. **Create an issue** on this GitHub repository with:
   - Your operating system
   - Python version (`python --version`)
   - The exact error message

## Customization

### Using a Different API

To connect to your own Futurama Quote Machine API:

1. Edit `server.py`
2. Change this line:
   ```python
   API_BASE_URL = "https://your-api-url.com/api"
   ```

### Adding New Features

The server code is well-documented. Look at the handler functions in `server.py` to see how to add new quote operations.

## File Structure

```
futurama-quote-machine-mcp/
├── server.py                    # Main MCP server code
├── run_server.sh               # Startup script (Mac/Linux)
├── run_server.bat              # Startup script (Windows)
├── requirements.txt            # Python dependencies
├── claude_desktop_config.json  # Example Claude Desktop config
├── README.md                   # This file
└── LICENSE                     # MIT License
```

## API Reference

This MCP server connects to a Futurama Quote Machine API with these endpoints:

- `GET /quotes` - List quotes (with pagination and filtering)
- `GET /random` - Get a random quote
- `GET /{id}` - Get specific quote by ID
- `POST /quotes` - Create new quote
- `PUT /{id}` - Update existing quote
- `DELETE /{id}` - Delete quote
- `GET /characters` - List all characters

For full API documentation, visit: [https://fqm.jeremyschroeder.net/api/](https://fqm.jeremyschroeder.net/api/)

## Contributing

Want to help improve this project?

1. Fork this repository
2. Create a feature branch (`git checkout -b feature/amazing-feature`)
3. Make your changes
4. Test thoroughly
5. Submit a pull request

### Ideas for contributions:
- Windows batch script improvements
- Better error handling
- Additional quote operations
- Integration with other quote APIs
- Improved documentation

## License

This project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.

## Related Projects

- [Futurama Quote Machine](https://github.com/jschroeder-mips/futurama_quote_machine) - The original Flask web app
- [MCP Official Documentation](https://modelcontextprotocol.io/) - Learn more about Model Context Protocol
- [Claude Desktop](https://claude.ai/download) - Download the Claude Desktop app

## Support

- 🐛 **Found a bug?** [Create an issue](https://github.com/YOUR-USERNAME/futurama-quote-machine-mcp/issues)
- 💡 **Have an idea?** [Start a discussion](https://github.com/YOUR-USERNAME/futurama-quote-machine-mcp/discussions)
- 📚 **Need help?** Check the troubleshooting section above

---

Made with ❤️ for the Futurama and Claude communities!