Skip to main content
Glama
README.md
<p align="center">
  <a href="https://gifs.vikram-gorla.com">
    <picture>
      <source media="(prefers-color-scheme: dark)" srcset="docs/assets/banner-dark.svg">
      <img src="docs/assets/banner-light.svg" alt="mcp-gifs: Give your AI a GIF button. GIF search powered by KLIPY." width="100%">
    </picture>
  </a>
</p>

<p align="center">
  <a href="https://gifs.vikram-gorla.com"><img alt="Try it live" src="https://img.shields.io/badge/try_it-live-ff5da2?style=for-the-badge&labelColor=1e1446"></a>
  <a href="https://klipy.com"><img alt="GIF search powered by KLIPY" src="https://img.shields.io/badge/GIF_search-powered_by_KLIPY-ffd93d?style=for-the-badge&labelColor=1e1446"></a>
  <a href="https://modelcontextprotocol.io"><img alt="MCP server" src="https://img.shields.io/badge/MCP-server-5bb8ff?style=for-the-badge&labelColor=1e1446"></a>
  <a href="#plug-it-in"><img alt="No auth, no API key" src="https://img.shields.io/badge/no_auth-no_API_key-3ddc97?style=for-the-badge&labelColor=1e1446"></a>
  <a href="LICENSE"><img alt="MIT license" src="https://img.shields.io/badge/license-MIT-ffa94d?style=for-the-badge&labelColor=1e1446"></a>
</p>

<p align="center">
  <a href="#plug-it-in"><b>Plug it in</b></a> ·
  <a href="#what-your-agent-gets"><b>Tools</b></a> ·
  <a href="#powered-by-klipy"><b>Powered by KLIPY</b></a> ·
  <a href="#run-your-own-copy"><b>Self-host</b></a>
</p>

## Your AI can write, code and plan. Now it can send a perfect facepalm.

**mcp-gifs** is a free, public [MCP](https://modelcontextprotocol.io) 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](https://klipy.com)**: reactions, memes, trending.
- 📚 **A free-licence backup.** When KLIPY has nothing, openly licensed GIFs
  from [Wikimedia Commons](https://commons.wikimedia.org) and
  [Openverse](https://openverse.org) 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.

<p align="center">
  <a href="https://gifs.vikram-gorla.com"><img src="docs/assets/homepage.png" alt="The mcp-gifs homepage: a yellow sticker-style page with the headline 'Give your AI a GIF button.' and a live GIF picker whose search box says 'Search KLIPY', with 'Powered by KLIPY' under it." width="88%"></a>
  <br><sub>Try the picker yourself at <a href="https://gifs.vikram-gorla.com">gifs.vikram-gorla.com</a>. It shows exactly what your agent gets back.</sub>
</p>

## 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**

```bash
claude mcp add --transport http gifs https://gifs.vikram-gorla.com/mcp
```

**Cursor**: `~/.cursor/mcp.json` (or `.cursor/mcp.json` in a project)

```json
{ "mcpServers": { "gifs": { "url": "https://gifs.vikram-gorla.com/mcp" } } }
```

**VS Code**: `.vscode/mcp.json`

```json
{ "servers": { "gifs": { "type": "http", "url": "https://gifs.vikram-gorla.com/mcp" } } }
```

<details>
<summary><b>Older Claude Desktop, other clients, and running it locally</b></summary>

On Claude Desktop builds without custom connectors, bridge through stdio with
[`mcp-remote`](https://www.npmjs.com/package/mcp-remote):

```json
{
  "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](https://github.com/modelcontextprotocol/inspector):
`npx @modelcontextprotocol/inspector` → transport *Streamable HTTP* → the URL.

**Local (stdio).** The package is not on npm; run it from a checkout
(Node 20+):

```bash
git clone https://github.com/vikramgorla/mcp-gifs && cd mcp-gifs
npm ci && npm run build
```

```json
{
  "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.

</details>

## 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](#safety-first). 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. |

<details>
<summary><b>See a full response</b> (real output from an open-licence search)</summary>

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):

```json
{
  "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:

```text
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.

</details>

### 🔥 `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

<p>
  <a href="https://klipy.com"><img alt="GIF search powered by KLIPY" src="https://img.shields.io/badge/GIF_search-powered_by_KLIPY-ffd93d?style=for-the-badge&labelColor=1e1446"></a>
</p>

The reaction GIFs come from **[KLIPY](https://klipy.com)**, and we play by
their rules. This section is how mcp-gifs follows KLIPY's
[attribution guidelines](https://docs.klipy.com/attribution) and
[integration requirements](https://docs.klipy.com/integration-requirements).
Requirement-by-requirement evidence (code, tests, screenshots) is in
[docs/KLIPY.md](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](docs/KLIPY.md).

**Running your own copy.** KLIPY is enabled by an API key from the
[KLIPY Partner Panel](https://partner.klipy.com):

- **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](https://klipy.com/support/terms-services). 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](https://wiki.creativecommons.org/wiki/Best_practices_for_attribution)
  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](https://commons.wikimedia.org/wiki/Commons:Reusing_content_outside_Wikimedia).

**Made with [Openverse](https://openverse.org), 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](https://github.com/vikramgorla/mcp-gifs/issues) 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)

```bash
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)

```bash
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:

```bash
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.

```bash
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](docs/DECISIONS.md).

## License

[MIT](LICENSE) for the code. GIFs returned by the server keep their own
licenses (KLIPY results are under [KLIPY's terms](https://klipy.com/support/terms-services)).
The landing page uses the Bricolage Grotesque typeface under the
[SIL Open Font License 1.1](docs/fonts/OFL-BricolageGrotesque.txt); 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.

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