🎭 Joke MCP Server

A simple yet powerful Model Context Protocol (MCP) server that brings humor to AI interactions. This MCP exposes random joke generation as tools that can be seamlessly integrated with Claude and other MCP-compatible clients.

✨ Features

• get_random_joke - Get a random joke with setup and punchline
• count_jokes - Get the total number of available jokes in the database
• Simple & Lightweight - Minimal dependencies, fast execution
• Easy Integration - Works with Claude Desktop and other MCP clients
• Well-Documented - Clear schemas and usage examples

🚀 Quick Start

Prerequisites

• Python 3.11 or higher
• pip package manager

Installation

# Clone the repository
git clone https://github.com/tehrimaly/mcp-joke.git
cd mcp-joke

# Create virtual environment
python -m venv venv

# Activate virtual environment
# On Windows:
venv\Scripts\Activate.ps1
# On macOS/Linux:
source venv/bin/activate

# Install dependencies
pip install -r requirements.txt

Running the Server

python joke-mcp.py

You should see:

🚀 Joke MCP Server starting...

📖 Usage

With Claude Desktop

Add this to your Claude Desktop configuration file:

macOS/Linux: ~/.config/Claude/claude_desktop_config.json Windows: %APPDATA%\Claude\claude_desktop_config.json

{
  "mcpServers": {
    "joke-mcp": {
      "command": "python",
      "args": ["/path/to/joke-mcp.py"]
    }
  }
}

Then restart Claude Desktop and you can ask Claude to tell jokes!

API Reference

get_random_joke

Returns a random joke with setup and punchline.

Input: None

Output:

Setup: Why don't scientists trust atoms?

Punchline: Because they make up everything!

count_jokes

Returns the total number of jokes available in the database.

Input: None

Output:

Total jokes: 5

🏗️ Project Structure

mcp-joke/
├── joke-mcp.py          # Main MCP server implementation
├── requirements.txt      # Python dependencies
├── README.md            # This file
├── .gitignore           # Git configuration
└── LICENSE              # MIT License

🔧 Technical Details

Built With

• Python 3.11+ - Programming language
• MCP SDK v1.0.0 - Model Context Protocol library
• Asyncio - Asynchronous programming

How It Works

The Joke MCP Server:

1. Starts an MCP server listening on stdio
2. Registers available tools with their schemas
3. Handles incoming requests from MCP clients
4. Returns formatted responses with joke data

# Tool registration example
@server.list_tools()
async def list_tools():
    return [
        Tool(
            name="get_random_joke",
            description="Get a random joke",
            inputSchema={...}
        )
    ]

# Tool execution
@server.call_tool()
async def call_tool(name: str, arguments: dict):
    if name == "get_random_joke":
        # Return random joke

📦 Dependencies

• mcp==1.0.0 - Model Context Protocol SDK

See requirements.txt for complete dependency list.

🎯 Current Features

✅ 5 built-in jokes ✅ Async/await support ✅ Clean error handling ✅ Simple schema-based tool definition ✅ Stdout logging

🔮 Future Enhancements

• [ ] Add joke categories (dad jokes, puns, dark humor)
• [ ] Implement difficulty levels
• [ ] Add joke ratings/feedback
• [ ] Connect to external joke APIs
• [ ] Persist user favorites
• [ ] Multi-language support
• [ ] Web UI for joke management

🤝 Contributing

Feel free to:

• Add more jokes to the database
• Improve documentation
• Report bugs
• Suggest new features

📝 License

This project is licensed under the MIT License - see LICENSE file for details.

🔗 Links

• GitHub: https://github.com/tehrimaly/mcp-joke
• MCP Specification: https://spec.modelcontextprotocol.io/
• Anthropic MCP Docs: https://modelcontextprotocol.io/

💡 Example Use Cases

1. AI Assistant Integration - Add humor to Claude interactions
2. Slack Bot - Integrate jokes into team communication
3. Learning Tool - Understand MCP implementation basics
4. Template - Use as a starting point for your own MCP servers

🐛 Troubleshooting

Issue: Module not found error

pip install -r requirements.txt

Issue: Port already in use The server uses stdio, not a port. This shouldn't occur.

Issue: Server won't start

• Check Python version (3.11+)
• Verify all dependencies installed
• Check for syntax errors

📧 Support

For issues, questions, or suggestions, please open a GitHub issue.

---

Made with ❤️ as part of the MCP learning journey