# MemeStack MCP

[![smithery badge](https://smithery.ai/badge/memestack/mcp)](https://smithery.ai/servers/memestack/mcp)

Hosted [Model Context Protocol](https://modelcontextprotocol.io) server for [MemeStack](https://memestack.ai) — a visual search engine for memes, infographics, charts, screenshots, and diagrams. Find images by meaning, by the OCR text printed inside them, or by visual similarity. AI-captioned, Lightning-ranked. Public, no auth, no signup — reads are free with daily quotas, generation is paid per call.

```
https://mcp.memestack.ai/mcp
```

Every list response returns citation blocks (markdown / HTML / plain) ready to paste with attribution. Image bytes are served from `https://api.memestack.ai/v1/images/{id}/{thumbnail|canonical|social-card}` — directly embeddable.

---

## Install

This is a hosted server. No clone, no build, no local environment. Point any MCP-aware client at the endpoint. Every snippet below was checked against the client's own documentation on 2026-10-11; the current list, with a link to each client's docs, is on [memestack.ai/mcp-server](https://memestack.ai/mcp-server).

### Claude Code

```bash
claude mcp add --transport http memestack https://mcp.memestack.ai/mcp
```

Or in a project `.mcp.json` — a remote server needs `"type": "http"`:

```json
{
  "mcpServers": {
    "memestack": {
      "type": "http",
      "url": "https://mcp.memestack.ai/mcp"
    }
  }
}
```

#### Or as a plugin (adds a skill)

This repo is also a Claude Code plugin marketplace. The plugin installs the same server plus a
`find-image` skill that tells Claude which tool answers which request and to keep the citation:

```bash
/plugin marketplace add Ed-Relight/memestack-mcp
/plugin install memestack@memestack
```

From a shell: `claude plugin marketplace add Ed-Relight/memestack-mcp` then
`claude plugin install memestack@memestack`. If you also use the claude.ai connector, Claude Code
lists the tools twice (one copy per server); either one is enough.

### Claude (claude.ai and Claude Desktop)

Add MemeStack from the [Connectors Directory](https://claude.ai/directory/memestack), or as a custom connector: **Customize → Connectors → + Add → Add custom connector** with the directory endpoint `https://mcp.memestack.ai/mcp/directory` (see [Chat apps](#chat-apps-directory-endpoint) below). Every plan can; a Free account can add one custom connector.

Claude Desktop's `claude_desktop_config.json` takes local servers only. To use the full `/mcp` endpoint there, bridge it with `mcp-remote`:

```json
{
  "mcpServers": {
    "memestack": {
      "command": "npx",
      "args": ["-y", "mcp-remote", "https://mcp.memestack.ai/mcp"]
    }
  }
}
```

### Cursor

[![Add the MemeStack MCP server to Cursor](https://cursor.com/deeplink/mcp-install-dark.svg)](https://cursor.com/en/install-mcp?name=memestack&config=eyJ1cmwiOiJodHRwczovL21jcC5tZW1lc3RhY2suYWkvbWNwIn0%3D)

One click opens Cursor's install prompt ([Cursor's install links](https://cursor.com/docs/context/mcp/install-links)). This repo is also a Cursor plugin (`.cursor-plugin/plugin.json` + `mcp.json`, with the `find-image` skill). Or edit `~/.cursor/mcp.json` (or per-project `.cursor/mcp.json`):

```json
{
  "mcpServers": {
    "memestack": { "url": "https://mcp.memestack.ai/mcp" }
  }
}
```

### VS Code (GitHub Copilot)

One click: the **Add to VS Code** link on [memestack.ai/mcp-server](https://memestack.ai/mcp-server) (a [`vscode:mcp/install`](https://code.visualstudio.com/api/extension-guides/ai/mcp) link, which GitHub does not render). Or `.mcp.json` at the workspace root, or `~/.copilot/mcp-config.json` for every workspace (the older `.vscode/mcp.json` with `"servers"` still loads, but VS Code now calls it deprecated):

```json
{
  "mcpServers": {
    "memestack": {
      "type": "http",
      "url": "https://mcp.memestack.ai/mcp"
    }
  }
}
```

### Devin Desktop (formerly Windsurf)

```bash
devin mcp add memestack https://mcp.memestack.ai/mcp
```

### Gemini CLI

```bash
gemini extensions install https://github.com/Ed-Relight/memestack-mcp
```

The extension manifest ([gemini-extension.json](gemini-extension.json)) points Gemini CLI at the hosted endpoint over Streamable HTTP (`httpUrl`). Without the extension:

```bash
gemini mcp add --transport http memestack https://mcp.memestack.ai/mcp
```

That writes `.gemini/settings.json` in the project; add `--scope user` for `~/.gemini/settings.json`.

### OpenAI Codex CLI

```bash
codex mcp add memestack --url https://mcp.memestack.ai/mcp
```

Or in `~/.codex/config.toml` (shared with the ChatGPT desktop app and the Codex IDE extension):

```toml
[mcp_servers.memestack]
url = "https://mcp.memestack.ai/mcp"
```

### Cline

In Cline's MCP settings (`cline_mcp_settings.json`), add the server with the camelCase `streamableHttp` type — without it Cline falls back to SSE and the endpoint answers 405:

```json
{
  "mcpServers": {
    "memestack": {
      "type": "streamableHttp",
      "url": "https://mcp.memestack.ai/mcp",
      "disabled": false,
      "autoApprove": []
    }
  }
}
```

The Remote Servers tab does the same (Transport "Streamable HTTP"), and so does the Cline CLI:

```bash
cline mcp add memestack https://mcp.memestack.ai/mcp --transport http --yes
```

### Zed

In Zed's settings (`zed: open settings file`), or Settings → AI → MCP Servers → Add Remote Server:

```json
{
  "context_servers": {
    "memestack": { "url": "https://mcp.memestack.ai/mcp" }
  }
}
```

### Goose

`goose configure` → Add Extension → Remote Extension (Streamable HTTP), or in `~/.config/goose/config.yaml` (Windows: `%APPDATA%\Block\goose\config\config.yaml`):

```yaml
extensions:
  memestack:
    type: streamable_http
    name: memestack
    enabled: true
    uri: "https://mcp.memestack.ai/mcp"
    headers: {}
    env_keys: []
    envs: {}
    timeout: 300
```

### LM Studio

LM Studio 0.3.17 or later: Program tab → Install → Edit `mcp.json`:

```json
{
  "mcpServers": {
    "memestack": { "url": "https://mcp.memestack.ai/mcp" }
  }
}
```

### Continue

Create `.continue/mcpServers/memestack.yaml` (MCP tools work in agent mode):

```yaml
name: MemeStack
version: 0.0.1
schema: v1
mcpServers:
  - name: memestack
    type: streamable-http
    url: https://mcp.memestack.ai/mcp
```

### Clients without remote MCP support

Bridge the endpoint with [`mcp-remote`](https://www.npmjs.com/package/mcp-remote):

```json
{
  "mcpServers": {
    "memestack": {
      "command": "npx",
      "args": ["-y", "mcp-remote", "https://mcp.memestack.ai/mcp"]
    }
  }
}
```

### Raw JSON-RPC (any HTTP client)

```bash
curl -X POST https://mcp.memestack.ai/mcp \
  -H "Content-Type: application/json" \
  -H "Accept: application/json, text/event-stream" \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/list"}'
```

Same endpoint for `initialize`, `tools/call`, `prompts/list`, `prompts/get`, `resources/list`, `resources/read`. Protocol version: `2025-06-18`.

### Chat apps (directory endpoint)

Chat apps get a second endpoint built for their connector directories:

```
https://mcp.memestack.ai/mcp/directory
```

It serves the **19 read tools only** — no paid tools, no payment offers, no daily quota — and its results never include images classified controversial (the `include_controversial` argument does not exist there; a by-id lookup of such an image answers "not found"). Prompts, resources and citations are the same as on `/mcp`. Add it by URL as a custom connector (Streamable HTTP, no authentication). Tool calls are rate-limited per minute; over the limit a call answers "Too many requests from this client" — wait a minute and retry. In ChatGPT (and other MCP Apps hosts) image results appear as a carousel of image cards.

Where each app keeps the setting (checked 2026-10-11):

- **Claude** — see [above](#claude-claudeai-and-claude-desktop).
- **ChatGPT** (web) — Plugins → + → Add custom MCP server → Server URL → Create as a plugin. Business and Enterprise/Edu; Pro can connect with read/fetch permissions in developer mode.
- **Mistral Le Chat** — Connectors → + Add Connector → Custom MCP Connector. Administrators (on Free, Pro and Student, the account owner).
- **Perplexity** — Account settings → Connectors → + Custom connector → Remote, transport Streamable HTTP. Pro, Max and Enterprise.
- **Microsoft Copilot Studio** — an agent's Tools page → Add a tool → New tool → Model Context Protocol, authentication None. Needs generative orchestration (not in the Copilot Studio for Teams plan).

---

## What's exposed

- **21 tools** — 19 free reads (8 of them with a daily quota, then a fraction of a cent per call — see [Pricing & payments](#pricing--payments)), 2 always paid (`generate_meme`, `submit_image`) — full catalog: [docs/tools.md](docs/tools.md)
- **6 prompts** — pre-baked workflows (topic search, top zapped, cite a meme, find a meme for a vibe, research meme evolution, trending): [docs/prompts.md](docs/prompts.md)
- **4 resources** — attribution guide, tag taxonomy, recent uploads feed, and the `memestack://top/{period}` template (top zapped images): [docs/resources.md](docs/resources.md)

### Tools at a glance

Discovery and search:

- `search_images` — semantic + keyword merged
- `search_charts` — charts/infographics with stored source metadata (dataset, citation, unit, regions, displayed period); not every chart — `search_images` has wider chart coverage. `publisher_only: true` (here and on `search_images`) keeps only charts imported from Our World in Data, USDA ERS, Eurostat or the EEA
- `search_text_in_image` — OCR-only search (find screenshots of specific quotes/text)
- `find_meme_for_text` — vibe-to-meme matcher for writing & social (only images tagged as memes, so it may come back empty; `search_images` covers every kind of image)
- `reverse_image_search` — phash-based "find this image" (accepts HTTPS or `data:` URLs)
- `find_similar` / `find_related` — neighbors of a known image (visual phash / semantic embedding)
- `browse_images`, `browse_by_tag`, `browse_by_category`, `list_categories`
- `popular_tags`, `tag_autocomplete`, `get_tag_profile`
- `get_image`, `get_user_profile`, `get_leaderboard`, `get_meme_variants`

Honest search results (rolling out — the server labels results only while its honest-search switch is on): when results carry `match`, `search_images`, `search_charts`, `search_text_in_image` and `find_meme_for_text` label each one `"strong"` (MemeStack has evidence it matches your query) or `"closest"` (the nearest thing it has). Strong results come first; closest ones are capped and marked `[closest match]` in the text view. The first page starts with a `note` when nothing matched strongly, and `has_more` says whether another page exists (`total` counts strong matches only). Without labels there is no `match`, `note` or `has_more`: a page shorter than `limit` is the last. With labels, `match_quality` sums the search up: `strong` (it has a strong match), `closest_only` (every result is only the nearest guess — do not present one as the answer) or `none`.

Reuse rights: every image carries `rights` — `source` (`publisher` / `creator` / `community`), the licence and its URL, the credit line (`attribution`), and `commercial_use` (`yes` / `no` / `unknown`; `unknown` is never a guess — Our World in Data charts can plot third-party data under its own terms, and MemeStack licenses no community upload). The `citation` says how to credit an image; `rights` says whether it may be reused. `cite_image` carries both.

Safe by default: every search and browse tool excludes images MemeStack classifies as controversial (partisan attack memes, slurs, dark humour — library content, but not a default result). Pass `include_controversial: true` on `search_images`, `search_charts`, `search_text_in_image`, `find_meme_for_text`, `reverse_image_search`, `find_similar`, `find_related`, `browse_images` or `browse_by_tag` to include them; each such result is marked `[controversial]` in the text view and carries `controversial: true` in the structured payload. By-id tools (`get_image`, `get_meme_variants`, `cite_image`) always answer and carry the flag. The REST equivalent is `?content=all` on the browse endpoints (`content=safe` is the default; any other value is `400 INVALID_CONTENT`).

Attribution:

- `cite_image` — canonical markdown/HTML/plain attribution blocks for one or many image IDs

Paid (agent payment rails — pay per call, no account):

- `generate_meme` — AI image generation via Grok Imagine. $0.08 standard / $0.20 quality, paid in sats or USDC. Returns a hosted, auto-tagged, CDN-served image URL.
- `submit_image` — submit an image by URL into the moderation review queue. $0.10 per submission, paid in sats or USDC, always paid, no free quota. No refund on moderation rejection (duplicate/nsfw/spam/low-quality) — the fee is the anti-spam mechanism; accepted images await human review before publication.

---

## Citations are baked in

Every list response includes a `citations_combined` block in three formats (markdown / HTML / plain) for the full set, plus a per-image `citation` on every individual image. Per-source rules differ — OWID images carry CC-BY 4.0 attribution to Our World in Data; Imgflip templates carry Imgflip attribution; direct uploads carry the uploader's display name and the MemeStack page URL — and Verified Creator uploads link the creator's name directly to their own website (mandatory attribution).

**Read `memestack://attribution-guide` once per session** for the license model and per-source rules. See [docs/resources.md](docs/resources.md).

---

## Pricing & payments

Reads are free with generous daily quotas; generation is paid per call. Every price is fixed in US dollars and paid at the current BTC/USD rate in sats, or in USDC. **No account, no API key** — payment itself is the auth, over two rails:

- **x402** (USDC on Base) — standard `x402/error` + `x402/payment` `_meta` flow; works out of the box with the Cloudflare Agents SDK's `withX402Client`. Heads-up: the SDK's default `maxPaymentValue` is $0.10 — `submit_image` ($0.10) fits it exactly; raise it to use `generate_meme` quality mode ($0.20).
- **L402** (Lightning sats, at the current BTC/USD rate) — on REST, standard `WWW-Authenticate: L402 macaroon="…", invoice="…"` challenge; retry with `Authorization: L402 <macaroon>:<preimage>`. Over MCP, an experimental `l402/payment` `_meta` extension carries the same proof.

| Tool group | Free quota | Over quota / price |
|---|---|---|
| Search & browse tools (`search_images`, `search_charts`, `browse_*`, `find_meme_for_text`, `search_text_in_image`) | 200 calls/day/IP | $0.005/call |
| `reverse_image_search` | 10 calls/day/IP | $0.02/call |
| `generate_meme` | always paid | $0.08 standard / $0.20 quality |
| `submit_image` | always paid | $0.10/submission |
| Everything else (`get_image`, `cite_image`, tags, categories, leaderboard, resources, prompts) | unmetered, free | — |

The sats amount for each price right now: `GET api.memestack.ai/v1/prices`. Paid REST twins (same prices, standard dual-header 402): `POST api.memestack.ai/v1/agent/generate`, `POST api.memestack.ai/v1/agent/reverse-search`, and `POST api.memestack.ai/v1/agent/submit` — see the [OpenAPI spec](https://api.memestack.ai/openapi.json).

One payment delivers at most one result — if a call fails or times out mid-generation, retry with the **same** payment proof to resume; you are never charged twice for one payment.

`submit_image` submissions land in the moderation review queue, not directly in the public gallery — there is **no refund if moderation rejects** the submission (duplicate/nsfw/spam/low-quality), since the review attempt itself is what the fee buys.

---

## Discovery surface

How MemeStack exposes itself to AI agents, beyond MCP:

| Surface | URL | Purpose |
|---|---|---|
| `llms.txt` | [memestack.ai/llms.txt](https://memestack.ai/llms.txt) | Concise human-readable summary + endpoint links |
| `ai-plugin.json` | [memestack.ai/.well-known/ai-plugin.json](https://memestack.ai/.well-known/ai-plugin.json) | ChatGPT plugin manifest |
| OpenAPI 3.1 | [api.memestack.ai/openapi.json](https://api.memestack.ai/openapi.json) | REST API the MCP wraps |
| Apex MCP mirror | [memestack.ai/mcp](https://memestack.ai/mcp) | Same MCP endpoint at apex (for naive scanners) |
| MCP server card | [mcp.memestack.ai/mcp/server-card](https://mcp.memestack.ai/mcp/server-card) | SEP-2127 server card (`application/mcp-server-card+json`); mirrored at `memestack.ai/mcp/server-card` and `memestack.ai/.well-known/mcp/server-card.json` |
| ARD manifest | [memestack.ai/.well-known/ard.json](https://memestack.ai/.well-known/ard.json) (alias `/.well-known/ai-catalog.json`) | Agentic Resource Discovery entry pointing at the server card |
| API catalog | [memestack.ai/.well-known/api-catalog](https://memestack.ai/.well-known/api-catalog) | RFC 9727 linkset: the REST API and the MCP server with their descriptions, docs and health endpoints |
| Agent Skill | [memestack.ai/.well-known/agent-skills/memestack/SKILL.md](https://memestack.ai/.well-known/agent-skills/memestack/SKILL.md) | agentskills.io skill — when to use MemeStack, REST quick start, tool costs, citation rule; index at `/.well-known/agent-skills/index.json` |
| x402 Bazaar | [api.cdp.coinbase.com/platform/v2/x402/discovery/resources](https://api.cdp.coinbase.com/platform/v2/x402/discovery/resources) | Coinbase's x402 discovery catalog — the paid REST endpoints (`/v1/agent/*`) and the MCP tools `generate_meme`/`submit_image`, with body schemas, examples and prices |
| oEmbed | [api.memestack.ai/v1/oembed](https://api.memestack.ai/v1/oembed) | Rich-type oEmbed for gallery URLs — `html` embed snippet with a via-MemeStack credit link |
| Sitemap | [memestack.ai/sitemap.xml](https://memestack.ai/sitemap.xml) | Sitemap index with image, page, and user sub-sitemaps |

---

## Source

The MCP server runs on Cloudflare Workers and proxies the public MemeStack REST API ([api.memestack.ai](https://api.memestack.ai)). The server's source is part of the larger MemeStack codebase, which is not publicly mirrored at this time. This repository hosts the public-facing docs, install snippets, and tool catalog so directory submissions and integrators can link to a stable, browsable surface.

If you want to fork the *protocol behavior* and self-host a similar gallery, the [REST API](https://api.memestack.ai/openapi.json) is documented and a sufficient backend for any MCP-style wrapper.

The `Dockerfile` in this repo is a thin proxy — it uses `mcp-remote` to bridge stdio MCP to the hosted HTTP endpoint, and exists only so MCP directories that require Dockerfile-based introspection (Glama, etc.) can validate the live tools/prompts/resources. End users should connect directly to `mcp.memestack.ai/mcp` per the [Install](#install) section above; the Docker image holds no source.

---

## License

MIT — covers the snippets and docs in this repo. The hosted MemeStack service is governed separately by [memestack.ai/terms](https://memestack.ai/terms). Images keep their owners' rights: only the open-data publisher charts (CC BY 4.0 or US public domain) and Verified Creator work come with license terms, set out in [memestack.ai/license](https://memestack.ai/license). MemeStack grants no license to any other image, and a `citation` block is attribution, not permission to reuse.