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, 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

git clone https://github.com/BitsofJeremy/futurama-quote-machine-mcp.git
cd futurama-quote-machine-mcp

Step 2: Set Up Python

On Mac:

# 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:

# 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:

# 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:

# 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:

{
  "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
• Claude Desktop app - Download here
• Internet connection (to fetch quotes from the API)

Installation Steps

1. Check if Python is installed:

   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:

   cd /path/to/futurama-quote-machine-mcp
   

5. Create a virtual environment:

   # Mac/Linux:
   python3 -m venv venv
   source venv/bin/activate
   
   # Windows:
   python -m venv venv
   venv\Scripts\activate
   

6. Install required packages:

   pip install mcp httpx
   

7. Make the script executable (Mac/Linux only):

   chmod +x run_server.sh
   

8. Test the server:

   # 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):

   {
     "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
2. Make sure it's in your PATH - try python3 instead of python

"Permission denied" (Mac/Linux)

chmod +x run_server.sh

"Module not found" errors

Make sure you activated the virtual environment and installed the packages:

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/ 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:

   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/

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 file for details.

Related Projects

• Futurama Quote Machine - The original Flask web app
• MCP Official Documentation - Learn more about Model Context Protocol
• Claude Desktop - Download the Claude Desktop app

Support

• 🐛 Found a bug? Create an issue
• 💡 Have an idea? Start a discussion
• 📚 Need help? Check the troubleshooting section above

---

Made with ❤️ for the Futurama and Claude communities!