🎭 Meme Genius Agent

Turn your ideas into viral gold with AI-powered meme genius!

An intelligent MCP (Model Context Protocol) agent that generates 2 copyright-free, hilarious pet memes from any text input. Powered by Google Gemini with smart emotion detection and template selection. Perfect for spicing up your DMs, social feeds, or creating viral content.

✨ Features

• One Input, Two Memes: Just provide text, get 2 hilarious variations
• Smart Template Selection: Auto-detects emotion and picks the best cat/dog template
• Copyright-Free: All memes are AI-generated, no copyright issues
• Simple API: Minimal parameters, maximum fun
• Gemini-Powered: Uses Google's latest image generation model

🚀 Quick Start

Prerequisites

• Node.js 18+
• Gemini API key (get one at Google AI Studio)

Installation

# Clone the repository
git clone https://github.com/Singularity-Engine/meme-genius-agent.git
cd meme-genius-agent

# Install dependencies
npm install

# Configure environment
cp .env.example .env
# Edit .env and add your GEMINI_API_KEY

Configuration

Create a .env file with:

GEMINI_API_KEY=your_gemini_api_key_here

Optional settings:

• GEMINI_MODEL - Model to use (default: gemini-2.5-flash-image-preview)
• OUTPUT_PATH - Where to save memes (default: /tmp/memes)
• PORT - Server port (default: 3002)
• REQUEST_TIMEOUT_MS - Timeout in ms (default: 60000)

Running the Server

# Development mode (with watch)
npm run dev

# Build and run
npm run build
npm start

# Or run directly
npm run run

The server will start on http://localhost:3002

📖 Usage

REST API

Endpoint: POST /generate

Request:

curl -X POST http://localhost:3002/generate \
  -H "Content-Type: application/json" \
  -d '{"text": "When you realize it'\''s Monday again"}'

Response:

{
  "success": true,
  "data": {
    "memes": [
      {
        "id": "meme_xxx",
        "image": "data:image/png;base64,...",
        "emotion": "tired",
        "animal": "cat",
        "template": "exhausted sleepy cat",
        "filename": "meme_xxx.png"
      },
      {
        "id": "meme_yyy",
        "image": "data:image/png;base64,...",
        "emotion": "tired",
        "animal": "dog",
        "template": "exhausted sleepy dog",
        "filename": "meme_yyy.png"
      }
    ],
    "text": "When you realize it's Monday again",
    "count": 2
  }
}

MCP Tool

Tool Name: generate_meme

Parameters:

• text (string, required): Your meme idea or text

Example with MCP Inspector:

npm run inspector

Then call the tool:

{
  "name": "generate_meme",
  "arguments": {
    "text": "Waiting for someone to text you back like..."
  }
}

🎨 Meme Templates

The generator automatically selects from 10+ templates based on detected emotion:

• Happy: Joyful grinning cats/dogs with wide eyes
• Sad: Grumpy, disappointed expressions
• Tired: Exhausted, sleepy faces (great for Monday memes!)
• Confused: Tilted head, puzzled looks
• Surprised: Shocked wide-eyed expressions
• Angry: Grumpy, fierce faces
• Silly: Derpy, goofy expressions with tongue out

🎯 Example Prompts

• "When you realize it's Monday again"
• "Waiting for someone to text you back like..."
• "When your boss schedules a meeting at 4:59pm on Friday"
• "Me pretending to understand the conversation"
• "When you hear the word 'walk'"
• "Trying to be productive but..."

🏗️ Architecture

agent-mcp/
├── src/
│   ├── server/
│   │   └── memeGeneratorMcpServer.ts    # Main MCP server
│   ├── services/
│   │   └── memeGenerator.ts              # Core meme generation logic
│   ├── providers/
│   │   └── geminiProvider.ts             # Gemini API integration
│   ├── types/
│   │   └── image.ts                      # TypeScript types
│   └── utils/
│       └── logger.ts                     # Logging utilities
├── package.json
└── tsconfig.json

🔧 Development

# Watch mode for development
npm run dev

# Build TypeScript
npm run build

# Clean build directory
npm run clean

# Run MCP inspector for debugging
npm run inspector

📝 Technical Details

• Provider: Google Gemini (gemini-2.5-flash-image-preview)
• Image Format: PNG, 1024x1024px
• Concurrent Requests: Managed automatically
• Timeout: 60 seconds default
• MCP SDK Version: 1.10.0

🤝 Contributing

This is a simplified, focused meme generator. The design philosophy:

• Simplicity First: One input parameter, minimal config
• No Bloat: Only essential features, no unnecessary complexity
• Single Provider: Gemini-only for consistency
• Fixed Format: 1024x1024 PNG, no size variations

If you want to contribute, please maintain this simplicity.

📄 License

MIT License - see LICENSE file

👨‍💻 Author

Abin trashwbin@gmail.com

---

Inspired by Quipple - A clever blend of "quip" (witty remark) and "ripple" (spreading widely), capturing how creative ideas ripple out into viral memes.