---

🌟 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 (MCP & Claude Skill): Give your AI assistant the power to search, download, and convert media on command!

---

🍿 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

---

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

---

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 Integration — Two Flows

gifboom supports two complementary ways to give AI agents GIF superpowers:

---

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 …

Setup (30 seconds):

pip install gifboom

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

The agent reads skills/gifboom/SKILL.md and instantly knows how to search, download, convert, trim, and optimize GIFs using shell commands.

---

Flow B — MCP Server (native tool calls)

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

AI Agent (Claude Desktop / LobeChat / …)
   │
   └─ calls MCP tools directly        ← search_gifs() / download_gif() / gif_to_video() …
         │
         └─ gifboom MCP server        ← no shell needed, returns structured JSON

Setup:

pip install 'gifboom[mcp]'

Add to your claude_desktop_config.json:

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

Available MCP tools: search_gifs, download_gif, gif_to_video, video_to_gif, extract_still, optimize_gif, open_key_page.

---

Which flow should I use?

	Flow A — CLI + Skill	Flow B — MCP
Requires shell	✅ yes	❌ no
Claude Desktop	❌	✅
Cursor / Antigravity	✅	✅
Structured JSON output	parse from stdout	native
Extra install	none	gifboom[mcp]

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

---

📦 Installation

Available on PyPI: gifboom

# Recommended — with uv (fastest)
uv add gifboom

# or pip
pip install gifboom

# or pipx (isolated global CLI)
pipx install gifboom

FFmpeg is required for all video/GIF conversion features:

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

Optional extras

pip install 'gifboom[mcp]'   # MCP server support
pip install 'gifboom[tui]'   # Interactive TUI (Textual)
pip install 'gifboom[dev]'   # Dev tools (pytest, ruff, mypy)

---

🚀 Quick Start

Step 1: Install (see above)

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
python3.11 -m pip install -e ".[dev]"
pytest tests/ -v

Check out our CONTRIBUTING.md for details.

---