---

📦 Installation

pip install gifboom        # pip
uv add gifboom             # uv (recommended)
pipx install gifboom       # pipx — isolated global CLI

FFmpeg is required for video/GIF conversion:

brew install ffmpeg        # macOS
sudo apt install ffmpeg    # Ubuntu / Debian

Optional extras:

pip install 'gifboom[mcp]'   # MCP server for Claude Desktop / LobeChat
pip install 'gifboom[tui]'   # Interactive terminal UI
pip install 'gifboom[dev]'   # Dev tools (pytest, ruff, mypy)

---

🌟 Why gifboom?

We loved tools like gifgrep for searching GIFs right from the terminal. But we kept asking:

"Where is the MP4 conversion? Where is video-to-GIF? What about trimming? And why can't my Claude / Cursor AI agent search and send GIFs for me??" 🤔

So we built gifboom — an open-source, lightning-fast Python CLI + MCP Server that does it all:

• 🔍 Multi-Provider Search — GIPHY, Tenor, KLIPY, and local folders in one command
• 🎬 GIF ↔ Video Conversion — Turn heavy 30MB GIFs into silky 2MB MP4s (or vice versa)
• 🖼️ Stills & Contact Sheets — Grab single PNG frames or full 3×3 video grids
• ✂️ Trim & Shrink — Slice out the funny 2 seconds and optimize color palettes
• 🤖 AI-Native — Give your AI assistant GIF superpowers via CLI Skill or MCP Server

---

🍿 Feature Tour

1. 🔍 Instant GIF Search

Find the perfect reaction without leaving your terminal (or let your script get JSON results).

# Pretty table format
gifboom search "excited reaction" --format table

# Pure JSON for scripts & AI
gifboom search "mind blown" --format json --limit 5

# Specific provider
gifboom search "fireworks" --provider tenor

---

2. 🎬 GIF ↔ Video Alchemy

Convert giant animated GIFs into lightweight MP4/WebM videos for Twitter, Discord, or web apps. Or turn video clips into crisp GIFs!

# Shrink 40MB GIF → 2MB MP4 (huge bandwidth saver!)
gifboom convert gif2video cat.gif -o cat.mp4

# Convert video clip to high-quality GIF
gifboom convert video2gif movie.mp4 -o clip.gif --start 00:01:20 --end 00:01:25

# Batch convert a whole folder of GIFs
gifboom convert batch ./my_gifs/ --format mp4 --out-dir ./my_videos/

---

3. 🖼️ Frame Extractor & Contact Sheets

Need a quick PNG snapshot or a grid breakdown of every keyframe?

# Extract single frame at 1.5 seconds
gifboom still dance.gif --at 1.5 -o frame.png

# Generate a 3×3 grid breakdown of 9 frames
gifboom sheet dance.gif --frames 9 --cols 3 -o grid.png

---

4. 🤖 AI Superpowers — Two Flows

Teach your AI agents (Claude Desktop, Cursor, Antigravity, LobeHub) how to handle GIFs autonomously!

Flow A — CLI + Agent Skill (shell-based)

Best for: Antigravity, Cursor, Windsurf, Claude Code — any agent with terminal access.

AI Agent
   ├─ reads skills/gifboom/SKILL.md   ← knows every command & flag
   └─ runs gifboom CLI via shell      ← gifboom search / convert / download …

pip install gifboom

# Copy the skill to your agent's skills folder:
cp -r skills/gifboom ~/.agents/skills/gifboom
# or for Antigravity:
cp -r skills/gifboom ~/.gemini/config/skills/gifboom

Flow B — MCP Server (native tool calls)

Best for: Claude Desktop, LobeChat, LibreChat — clients without shell access.

AI Agent
   └─ calls MCP tools directly   ← search_gifs() / gif_to_video() / …
         └─ gifboom MCP server   ← no shell needed, structured JSON

pip install 'gifboom[mcp]'

claude_desktop_config.json:

{
  "mcpServers": {
    "gifboom": {
      "command": "gifboom",
      "args": ["mcp"]
    }
  }
}

	Flow A — CLI + Skill	Flow B — MCP
Requires shell	✅	❌
Claude Desktop	❌	✅
Cursor / Antigravity	✅	✅
Extra install	none	gifboom[mcp]

💡 Both flows can be used simultaneously — install once, integrate both ways.

---

🚀 Quick Start

Step 1: Install

pip install gifboom
brew install ffmpeg   # Required for video magic ✨

Step 2: Get Free API Keys in 1-Click 🔑

Don't have API keys yet? No problem! gifboom will launch the developer portals for you:

# Open developer portals directly in your web browser:
gifboom keys giphy    # Opens GIPHY Developer Dashboard
gifboom keys tenor    # Opens Tenor / Google Cloud Console

# Save your key locally:
gifboom config set GIPHY_API_KEY=your_secret_key_here

Step 3: Boom! 💥

# Download the top "happy cat" GIF directly
gifboom download "q:happy cat" -o ~/Downloads/happy_cat.gif

# Convert to MP4
gifboom convert gif2video ~/Downloads/happy_cat.gif -o ~/Downloads/happy_cat.mp4

# Batch convert a whole folder of GIFs
gifboom convert batch ./my_gifs/ --format mp4 --out-dir ./my_videos/

---

⚡ Cheat Sheet & Recipes

Task	Command
Quick search & copy URL	gifboom search "party parrot"
Download specific URL	gifboom download https://media.giphy.com/... -o meme.gif
Discord Emoji Optimizer	gifboom convert optimize emote.gif --colors 64 -o emote_small.gif
Trim awkward start/end	gifboom convert trim laugh.gif --start 0.5 --end 2.5 -o clean_laugh.gif
WebM for websites	gifboom convert gif2video hero.gif -o hero.webm --crf 28
Check cache size	gifboom cache stats

---

🌐 Provider Support

Provider	Free Tier	Setup Command	Env Variable
GIPHY	100 req/hr (dev key)	gifboom keys giphy	GIPHY_API_KEY
Tenor	Generous (Google Cloud)	gifboom keys tenor	TENOR_API_KEY
KLIPY	Free beta	gifboom keys klipy	KLIPY_API_KEY
Local	Unlimited 💾	No key needed	—

---

🤝 Contributing

We love pull requests! Whether it's adding new GIF providers, improving conversion speed, or writing documentation:

git clone https://github.com/MIt9/gifboom.git
cd gifboom
pip install -e ".[dev]"
pytest tests/ -v

Check out our CONTRIBUTING.md for details.

---