mcp-gifs
Search openly licensed GIFs and retrieve full details for a specific GIF.
Use
search_gifsto find GIFs by keyword, with optional result limit, safety filter, source selection (Wikimedia Commons/Openverse/auto), and maximum file size.Results include direct GIF URLs, previews, dimensions, file size, animation/frame info, source, license, page URL, and ready-made attribution.
Use
get_gifwith an id from search results to refetch one GIF’s details; it returns whether it was found and the GIF or null.Supports only
safeandmoderatecontent filtering, with no unfiltered mode.
Fallback source for openly licensed animated GIFs. Used to fill gaps when Wikimedia Commons results are insufficient, returning GIF results with licensing and attribution metadata while filtering mature content.
Primary source for openly licensed animated GIFs. Provides keyword search and GIF lookup with metadata such as direct GIF and preview URLs, dimensions, file size, frame count, author, license, attribution text, and Commons page URL.
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type
@followed by the MCP server name and your instructions, e.g., "@mcp-gifs search for a safe animated GIF of a rocket launch"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
Your AI can write, code and plan. Now it can send a perfect facepalm.
mcp-gifs is a free, public MCP server that gives Claude, Cursor, VS Code and any other MCP client a GIF button. Your agent asks for "mind blown" and gets back the same kind of reaction GIFs people send in WhatsApp or Teams, each with a direct link, a preview, its size and a credit line ready to show.
🎉 The GIFs people actually send. GIF search is powered by KLIPY: reactions, memes, trending.
📚 A free-licence backup. When KLIPY has nothing, openly licensed GIFs from Wikimedia Commons and Openverse step in. The two are never mixed in one list.
🔌 Zero setup. One URL. No sign-in, no API key, no sessions.
🧸 Safe by default. Unsafe searches are refused and KLIPY is asked for G-rated GIFs unless you pick
moderate.🏷️ Credit built in. Every result says where it came from, and agents are told to show it.
Related MCP server: Pixabay MCP Server
Plug it in
The endpoint is https://gifs.vikram-gorla.com/mcp (Streamable HTTP,
stateless). Pick your client and you are done in about 30 seconds.
Claude (claude.ai and the desktop app): Settings → Connectors → Add custom connector, then paste the URL. No OAuth needed.
Claude Code
claude mcp add --transport http gifs https://gifs.vikram-gorla.com/mcpCursor: ~/.cursor/mcp.json (or .cursor/mcp.json in a project)
{ "mcpServers": { "gifs": { "url": "https://gifs.vikram-gorla.com/mcp" } } }VS Code: .vscode/mcp.json
{ "servers": { "gifs": { "type": "http", "url": "https://gifs.vikram-gorla.com/mcp" } } }On Claude Desktop builds without custom connectors, bridge through stdio with
mcp-remote:
{
"mcpServers": {
"gifs": { "command": "npx", "args": ["-y", "mcp-remote", "https://gifs.vikram-gorla.com/mcp"] }
}
}Any other client that speaks MCP Streamable HTTP works too: no session id, no
auth header. Poke at it with the
MCP Inspector:
npx @modelcontextprotocol/inspector → transport Streamable HTTP → the URL.
Local (stdio). The package is not on npm; run it from a checkout (Node 20+):
git clone https://github.com/vikramgorla/mcp-gifs && cd mcp-gifs
npm ci && npm run build{
"mcpServers": {
"gifs": {
"command": "node",
"args": ["/absolute/path/to/mcp-gifs/dist/stdio.js"],
"env": { "KLIPY_API_KEY": "optional: your own KLIPY key" }
}
}
}This works in Claude Desktop (claude_desktop_config.json), Cursor and other
stdio clients. Without KLIPY_API_KEY the local server uses only the open
sources.
What your agent gets
Three tools. Ask for a vibe, get GIFs.
Tool | What it does |
🔎 | Find GIFs by a few words: "facepalm", "happy dance", "thank you". |
🔥 | What people are sending right now, like the first tab of a GIF picker. |
🎯 | Look up one GIF again by the id that search returned. |
🔎 search_gifs
Argument | Type | Default | Notes |
| string (1-200 chars) | required | Keywords, e.g. |
| integer 1-25 |
| Maximum results. |
|
|
| See Safety. No unfiltered mode. |
|
|
|
|
| number 0.1-100 |
| Prefer files up to this size. KLIPY: picks a smaller rendition. Open sources: skips larger files. |
| string like | none | KLIPY only: results tuned to a language and region. |
On the public server most searches come back from KLIPY with source: "klipy"
and the same fields (plus mp4Url and webpUrl). This example is an
open-licence result because it shows every license field.
Returns structuredContent plus a readable markdown summary. Real output for
{"query": "rocket launch", "limit": 2} (2026-11-14):
{
"query": "rocket launch",
"safety": "safe",
"count": 2,
"results": [
{
"id": "wikimedia:File:Rocket Launch (2).gif",
"title": "Rocket Launch (2)",
"url": "https://upload.wikimedia.org/wikipedia/commons/7/71/Rocket_Launch_%282%29.gif",
"previewUrl": "https://upload.wikimedia.org/wikipedia/commons/thumb/7/71/Rocket_Launch_%282%29.gif/240px-Rocket_Launch_%282%29.gif",
"width": 270,
"height": 270,
"fileSizeBytes": 6264294,
"animated": true,
"frameCount": 150,
"source": "wikimedia-commons",
"pageUrl": "https://commons.wikimedia.org/wiki/File:Rocket_Launch_(2).gif",
"author": "Glosome",
"authorUrl": "https://commons.wikimedia.org/wiki/User:Glosome",
"license": "CC BY-SA 4.0",
"licenseUrl": "https://creativecommons.org/licenses/by-sa/4.0",
"attributionRequired": true,
"attribution": "\"Rocket Launch (2)\" by Glosome, CC BY-SA 4.0 (https://creativecommons.org/licenses/by-sa/4.0), via Wikimedia Commons: https://commons.wikimedia.org/wiki/File:Rocket_Launch_(2).gif",
"description": "A model rocket launching in slow-motion."
},
{
"id": "wikimedia:File:Rocket Launch (3).gif",
"title": "Rocket Launch (3)",
"url": "https://upload.wikimedia.org/wikipedia/commons/5/5c/Rocket_Launch_%283%29.gif",
"...": "..."
}
],
"sourcesQueried": ["wikimedia-commons"],
"notes": []
}The text content for the same call looks like:
Found 2 GIFs for "rocket launch" (safety: safe; sources: wikimedia-commons).
1. **Rocket Launch (2)**
- GIF: https://upload.wikimedia.org/wikipedia/commons/7/71/Rocket_Launch_%282%29.gif
- Preview: https://upload.wikimedia.org/wikipedia/commons/thumb/7/71/Rocket_Launch_%282%29.gif/240px-Rocket_Launch_%282%29.gif
- 270×270, 6.0 MB, animated, 150 frames; source: wikimedia-commons
- License: CC BY-SA 4.0 (https://creativecommons.org/licenses/by-sa/4.0) (attribution required)
- Attribution: "Rocket Launch (2)" by Glosome, CC BY-SA 4.0 (https://creativecommons.org/licenses/by-sa/4.0), via Wikimedia Commons: https://commons.wikimedia.org/wiki/File:Rocket_Launch_(2).gif
- id: `wikimedia:File:Rocket Launch (2).gif`
...Field notes:
animated: truemeans the Commons frame count is above 1.nullmeans the source cannot tell us (non-Commons Openverse results).previewUrlis a reduced Commons thumbnail: about 320 px wide when the original is larger, or a smaller/thumb/rendition (for example 240 px) when the original is already narrower than 320 px, so a long animation that is only a few hundred pixels wide is not served as a multi-megabyte preview.notesexplains fallbacks, blocked queries and upstream problems.
🔥 trending_gifs
Only offered when KLIPY is configured (it is on the public server).
Argument | Type | Default | Notes |
| integer 1-25 |
| |
|
|
| Sent to KLIPY as |
| number 0.1-100 |
| |
| string like | none |
Same output shape as search_gifs, with query: "". This is the default tab
of a chat-app GIF picker.
🎯 get_gif
Argument | Type | Default | Notes |
| string | required | An |
|
|
|
Returns { "found": boolean, "gif": <same shape as above> | null }.
Powered by KLIPY
The reaction GIFs come from KLIPY, and we play by their rules. This section is how mcp-gifs follows KLIPY's attribution guidelines and integration requirements. Requirement-by-requirement evidence (code, tests, screenshots) is in docs/KLIPY.md.
What users and agents see
The landing page has a live GIF search whose box says "Search KLIPY", with "Powered by KLIPY" (linking to klipy.com) directly under it, and a "GIF search powered by KLIPY" credit in the footer.
Every KLIPY result has
source: "klipy"and anattributionline that contains "Powered by KLIPY". The resultnotes, the tool descriptions and the server instructions tell agents to show it with the GIFs, to keep KLIPY's order, to load media from the returned URLs, not to mix KLIPY GIFs with other providers, and to label any search box "Search KLIPY".
How results are handled
Order and composition: Search and Trending results are returned in KLIPY's order. mcp-gifs does not reorder, filter or replace them. Content filtering is KLIPY's
ratingparameter (safe→g,moderate→pg-13) plus whatever is configured in the KLIPY Partner Panel. If a size cap rules out the larger renditions, the smallest one is used instead of dropping the GIF.No mixing: a response holds KLIPY results or open-licence results, never both. Open sources are used only when KLIPY has no match or is unavailable, and
notessays so.Media: never downloaded, stored, proxied or re-hosted. Results carry KLIPY's own media URLs (GIF, MP4, WebP) and clients load them directly.
Ads: no
customer_idis sent, so KLIPY returns no ad items.API key: read from the server environment only, never accepted from clients, never returned in errors or notes.
Server-side use. An MCP server calls KLIPY from the server, not from the
end user's device. KLIPY API responses are cached only as long as KLIPY's
own Cache-Control / Expires headers allow (never, if they say not to or
say nothing); there is no fixed cache time. Media is not cached. KLIPY asks for
written approval for server-side integrations; the request is described in
docs/KLIPY.md.
Running your own copy. KLIPY is enabled by an API key from the KLIPY Partner Panel:
stdio: add
"env": { "KLIPY_API_KEY": "..." }to the server entry in your MCP client config.Vercel via this repo's GitHub Actions: add a repository secret named
KLIPY_API_KEY; the preview and production workflows pass it tovercel deploy --env, and each preview is smoke-tested with a "facepalm" search.Cloudflare Workers:
npx wrangler secret put KLIPY_API_KEY.
Without a key, trending_gifs is not offered and search uses only the open
sources. KLIPY test keys are limited to 100 calls per hour; production keys
are requested in the Partner Panel and need KLIPY's approval. Self-hosters
must follow KLIPY's terms and attribution rules with their own key.
Show the credit
Good GIFs deserve credit. This server does not host or relicense anything, so when your app or agent shows a GIF, show where it came from.
KLIPY results (source: "klipy") are provided under
KLIPY's terms. Show
"Powered by KLIPY" with them, keep them in the order returned, load media
from the returned URLs, and do not mix them with GIFs from other providers in
the same set. If you build a search box on top of them, its placeholder must
read "Search KLIPY".
Open-licence results (wikimedia-commons, openverse) stay under their
own license, which is usually Creative Commons (BY, BY-SA), CC0 or public
domain. When you show one:
Show the
attributionstring (or equivalent: title, author, license with link, and source page) next to it. It is pre-built in the TASL style recommended by Creative Commons and Wikimedia.Keep the license link. For BY-SA files, adaptations must be shared under the same license. If you modify a GIF (crop, resize, caption), say so.
attributionRequired: false(e.g. CC0/public domain) means credit is not legally required, but it is still good practice.Check
pageUrlfor the authoritative license; metadata can be imperfect. Some files carry extra restrictions such as trademarks or personality rights.See Wikimedia's guide: Reusing content outside Wikimedia.
Made with Openverse, not endorsed by Openverse.
Not affiliated with or endorsed by the Wikimedia Foundation. GIF files are
loaded directly from the original hosts (mostly upload.wikimedia.org).
Safety first
GIFs should be fun for everyone in the chat.
safe(default) andmoderateare the only modes; there is no unfiltered option.Queries containing blocked terms are refused before any upstream call.
KLIPY: content is filtered by KLIPY itself through the
ratingparameter (safe→ G,moderate→ PG-13) and the KLIPY Partner Panel settings. mcp-gifs does not drop or reorder KLIPY results (KLIPY's rules require the result set to stay as KLIPY composed it).Open sources: results are dropped when their title, description, categories (Commons) or tags (Openverse) contain blocked terms.
moderateblocks sexual/explicit and hate content;safealso blocks violence, gore, self-harm and hard drugs.Openverse is never asked for mature content, and results flagged
mature(always) or sensitive (safemode) are dropped.Medical and food phrases that contain an otherwise blocked word (for example "breast cancer", "breastfeeding", "chicken breast") are allowed. The same words used alone, or next to other blocked terms, are still refused.
Best effort only. Wikimedia Commons has no official content rating, so filtering relies on keywords. It can miss things and can over-block. Please open an issue for misses.
Limits
Hosted endpoint: the only cap is the Vercel Firewall rule
mcp-rate-limit(path prefix/mcp, fixed window of 60 s, 60 requests per IP, HTTP 429 when exceeded; 1 rule and 1 million allowed requests/month are included on Hobby). In-memory per-IP and global limiters in the Edge Function are off by default and are not set on the public deployment. Self-hosters on other platforms can enable them withRATE_LIMIT_PER_IPandRATE_LIMIT_GLOBAL(requests per 60 s; unset or 0 disables). Enabled in-memory limiters return HTTP 429 withRetry-After: 60. A self-hosted Cloudflare Worker can use theRATE_LIMITERandGLOBAL_RATE_LIMITERbindings instead.KLIPY results are cached only as long as KLIPY's response headers allow. Open-licence results are cached for 10 minutes (
CACHE_TTL_SECONDS), or less when they are a fallback for a KLIPY search. Media is never cached.Upstream: Commons is queried sequentially with a descriptive User-Agent (
mcp-gifs/<version> (https://github.com/vikramgorla/mcp-gifs)) andRetry-Afteris respected. Anonymous Openverse is limited to about 20 requests/minute and 200/day per server IP and often returns 504s, so it is only a fallback: insource=autoit is given a 2 s timeout (8 s when Openverse is requested explicitly) and pauses for 60 s after a failure.
Run your own copy
Want your own GIF button? Fork it and deploy in a few minutes.
The public instance is on Vercel Hobby. That plan is free and pauses when included usage is exhausted; it does not start billing. Requirements to run your own copy: Node 20+, and either a Vercel Hobby account or a Cloudflare account.
Vercel (how the public instance is hosted)
npm ci
npm test
npx vercel login # once, on a Hobby (free) team
npx vercel # preview
npx vercel --prod # production, default *.vercel.app URLapi/index.ts is an Edge Function that reuses the shared HTTP core
(src/app.ts) and serves /, /health and /mcp. vercel.json rewrites
those paths to the function. CI deploys through GitHub Actions with the
Vercel CLI (VERCEL_TOKEN, VERCEL_ORG_ID, VERCEL_PROJECT_ID repository
secrets). Vercel's own Git auto-deploy is not used, so a push does not
deploy twice. In-memory rate limits stay off unless you set
RATE_LIMIT_PER_IP and/or RATE_LIMIT_GLOBAL (the public project does
not set them).
Cloudflare Workers (optional self-host)
npm ci
npm test
npm run dev # wrangler dev on http://localhost:8787 (/, /health, /mcp)
npx wrangler login # once
npm run deploy # wrangler deploy → https://mcp-gifs.<subdomain>.workers.devwrangler.jsonc deploys only to the default workers.dev URL. It uses:
RATE_LIMITER: Workers Rate Limiting binding (60 requests / 60 s / IP). Changenamespace_idif4711clashes with another binding in your account, or remove the block to disable rate limiting.GLOBAL_RATE_LIMITER: 25 requests / 60 s on a constantglobalkey.CACHE_TTL_SECONDS: cache TTL for open-licence results (default600). KLIPY results follow KLIPY's headers instead.
Quick manual check against a running server:
curl -s -X POST http://localhost:8787/mcp \
-H 'Content-Type: application/json' -H 'Accept: application/json, text/event-stream' \
-d '{"jsonrpc":"2.0","id":1,"method":"tools/call","params":{"name":"search_gifs","arguments":{"query":"cat","limit":2}}}'Hacking on it
PRs welcome, especially new example searches and safety fixes.
npm run typecheck && npm run lint && npm test
npm run smoke # live APIs + stdio (not in CI)
MCP_URL=http://localhost:8787/mcp npm run smoke # also test an HTTP endpoint
npm run stdio # run the stdio server from sourceLayout: src/sources/ (KLIPY, Commons and Openverse clients and mapping),
src/search.ts (provider order, fallback, caching), src/safety.ts,
src/server.ts (MCP tools), src/landing.ts (the homepage),
src/app.ts (shared HTTP), src/vercel.ts /
api/index.ts (Vercel Edge entry), src/worker.ts (Workers self-host entry), src/stdio.ts.
Design rationale: docs/DECISIONS.md.
License
MIT for the code. GIFs returned by the server keep their own
licenses (KLIPY results are under KLIPY's terms).
The landing page uses the Bricolage Grotesque typeface under the
SIL Open Font License 1.1; it is
served from this server at /assets/bricolage-v1.woff2, so the page makes no
third-party requests apart from loading GIFs from their providers.
Available Tools
2 toolsget_gifGet GIFARead-onlyIdempotent
Fetch full details for one GIF by the id returned from search_gifs (e.g. "wikimedia:File:Foo.gif" or "openverse:").
Inputs: id (required), safety. Returns: gif, found
search_gifsSearch GIFsARead-onlyIdempotent
Search openly licensed animated GIFs by keywords (e.g. "cat", "rocket launch", "dancing"). Returns direct GIF URLs, preview URLs, dimensions, license and a ready-made attribution string. English keywords work best.
Inputs: query (required), limit, safety, source, +1 more. Returns: count, notes, query, safety, +2 more
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
TDQS
Scored across 2 tools
search_gifs and get_gif have clearly distinct purposes: one discovers GIFs by keyword, the other retrieves details for a specific GIF ID. There is no meaningful overlap that would cause misselection.
Both tools follow a consistent snake_case verb_noun pattern: search_gifs and get_gif. The singular/plural difference reflects the natural distinction between searching many GIFs and fetching one.
With only two tools, the surface feels thin even for a focused GIF server. Basic discovery is covered, but additional lightweight operations like trending or random GIF retrieval are absent.
The core workflow—search for GIFs and inspect a specific result—is fully covered. Minor gaps such as trending/popular lists or random selection can be worked around via keyword searches.
Maintenance
Related MCP Connectors
Search GIFs and retrieve animated media URLs; show reactions in clients that support MCP Apps.
Image search for AI agents: 1.85M openly licensed images with source, license and attribution.
Openverse MCP — Creative-Commons-licensed image + audio search.
Search millions of CC0 public-domain AI images: previews, dimensions, provenance, license.
Related MCP Servers
- AlicenseAqualityFmaintenanceEnables AI models to search, retrieve, and utilize GIFs from Giphy with features like content filtering, multiple search methods, and comprehensive metadata.3238 npm36MIT
- AlicenseBqualityDmaintenanceEnables AI assistants to search for and retrieve images, illustrations, and videos directly from Pixabay. It provides specialized tools for discovering diverse media content like photos and animations using the Pixabay API.2MIT
- AlicenseBqualityDmaintenanceEnables searching and retrieving images from Wikipedia Commons with detailed metadata including licenses and authors.247 npm11MIT
- AlicenseAqualityDmaintenanceEnables AI assistants to search for images on Wikimedia Commons, returning structured metadata and a composite thumbnail grid for visual comparison.1104 npm3MIT