Futurama Quote Machine MCP Server

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