Skip to main content
Glama

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/mcp

Cursor: ~/.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

🔎 search_gifs

Find GIFs by a few words: "facepalm", "happy dance", "thank you".

🔥 trending_gifs

What people are sending right now, like the first tab of a GIF picker.

🎯 get_gif

Look up one GIF again by the id that search returned.

🔎 search_gifs

Argument

Type

Default

Notes

query

string (1-200 chars)

required

Keywords, e.g. cat, rocket launch. English works best.

limit

integer 1-25

8

Maximum results.

safety

safe | moderate

safe

See Safety. No unfiltered mode.

source

auto | klipy | wikimedia | openverse

auto

auto = KLIPY first; if KLIPY has no match (or no key is configured), Commons first and Openverse fills gaps.

max_size_mb

number 0.1-100

10

Prefer files up to this size. KLIPY: picks a smaller rendition. Open sources: skips larger files.

locale

string like en_US

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: true means the Commons frame count is above 1. null means the source cannot tell us (non-Commons Openverse results).

  • previewUrl is 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.

  • notes explains fallbacks, blocked queries and upstream problems.

🔥 trending_gifs

Only offered when KLIPY is configured (it is on the public server).

Argument

Type

Default

Notes

limit

integer 1-25

8

safety

safe | moderate

safe

Sent to KLIPY as rating=g / pg-13.

max_size_mb

number 0.1-100

10

locale

string like en_US

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

id

string

required

An id from search_gifs, e.g. klipy:<slug>, wikimedia:File:Spinning Dancer.gif or openverse:<uuid>.

safety

safe | moderate

safe

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 an attribution line that contains "Powered by KLIPY". The result notes, 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 rating parameter (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 notes says 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_id is 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 to vercel 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 attribution string (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 pageUrl for 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) and moderate are 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 rating parameter (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. moderate blocks sexual/explicit and hate content; safe also blocks violence, gore, self-harm and hard drugs.

  • Openverse is never asked for mature content, and results flagged mature (always) or sensitive (safe mode) 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 with RATE_LIMIT_PER_IP and RATE_LIMIT_GLOBAL (requests per 60 s; unset or 0 disables). Enabled in-memory limiters return HTTP 429 with Retry-After: 60. A self-hosted Cloudflare Worker can use the RATE_LIMITER and GLOBAL_RATE_LIMITER bindings 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)) and Retry-After is 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: in source=auto it 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 URL

api/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.dev

wrangler.jsonc deploys only to the default workers.dev URL. It uses:

  • RATE_LIMITER: Workers Rate Limiting binding (60 requests / 60 s / IP). Change namespace_id if 4711 clashes with another binding in your account, or remove the block to disable rate limiting.

  • GLOBAL_RATE_LIMITER: 25 requests / 60 s on a constant global key.

  • CACHE_TTL_SECONDS: cache TTL for open-licence results (default 600). 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 source

Layout: 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 tools
get_gifGet GIFA
Read-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 GIFsA
Read-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

    A4/5.0

    Scored across 2 tools

    Disambiguation5/5

    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.

    Naming Consistency5/5

    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.

    Tool Count3/5

    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.

    Completeness4/5

    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

    ActivityMaintained
    ResponsivenessNo recent community issues

    Related MCP Connectors

    Related MCP Servers

    • A
      license
      A
      quality
      F
      maintenance
      Enables AI models to search, retrieve, and utilize GIFs from Giphy with features like content filtering, multiple search methods, and comprehensive metadata.
      3
      238 npm
      36
      MIT
    • A
      license
      B
      quality
      D
      maintenance
      Enables searching and retrieving images from Wikipedia Commons with detailed metadata including licenses and authors.
      2
      47 npm
      11
      MIT