HanapMeme
Ingests GIPHY search results and GIFs as an optional source for the searchable meme library, with source credit and safety review.
Uses OpenAI models for image annotation, embeddings, search reranking, meme caption/template selection, and image generation.
Uses Vercel Blob as a persistent store for takedown/report statuses so removed memes stay hidden on deployed instances.
This server does not currently have a deployable release on Glama. Follow the repository's setup instructions to install and configure it for your MCP client, including any required credentials and local dependencies.
HanapMeme
It is Google for Pinoy memes, but you search in Taglish feelings.
Live: https://hanap-meme.vercel.app · MCP: https://hanap-meme.vercel.app/api/mcp
Type meme para sa late na naman sa standup and get matching memes and GIFs with source credit. There are three ways in:
A website with search, a gallery, and a meme generator.
A REST API.
An MCP server (Streamable HTTP), so Codex, ChatGPT, or Claude can search and make memes in a conversation.

Quickstart (5 min)
You need Node 24 (LTS, see .nvmrc), npm, and your own OpenAI API key.
git clone https://github.com/ahleksu/hanap-meme.git
cd hanap-meme
npm i
cp .env.example .env.local # then put your OPENAI_API_KEY in .env.local
cp sources.example.yaml sources.yaml
npm run ingest -- --limit 30 # builds your own meme library (about 15 min)
npm run templates # skips the 8 AI templates that are already in the repo
npm run devOpen http://localhost:3000.
Related MCP server: memewright
Works without an API key
If OPENAI_API_KEY is not set, the app still runs:
Search uses BM25 keyword scoring (a standard text-ranking formula) with a Taglish synonym map. For example,
pagodalso matchestired,antok, andmonday.Ingest stores Imgflip templates, inbox images, and the AI templates with their names as descriptions. It skips scraped pages and GIPHY, because those images need an AI safety review before the app can show them.
The generator uses the keyword-matched template and a plain caption.
A fresh clone with no library shows the empty state: "Wala pang memes. Run npm run ingest or drop images into data/inbox/."
Assets and rights
The code is MIT. Scraped images are not in this repository, and the MIT license does not cover them. Each teammate builds a local library with npm run ingest. catalog.json holds the provenance of the maintainer's library: source URL, platform, author, and retrieval date. It holds no image bytes. The 8 AI templates in public/templates/ and the stickers in public/brand/ are original AI images and are in the repository. Removal requests are honored within 48 hours. Read ASSET_LICENSE.md for the full terms.
Safety rules in the code:
The AI review flags possible minors, private individuals, explicit content, and hateful content. A flagged image gets status
excludedand is never served.Report sets status
takedownat once. Onlyactivememes leave the server, in the UI, the REST API, and MCP.Images are served by
/api/memes/:id/image, which checks the status first. They are not inpublic/, so nobody can fetch a removed image by its file URL.The scraper obeys
robots.txt, sends at most 1 request every 2 seconds per host, and identifies itself asHanapMemeBot/0.1 (+<contact_url>).
Architecture
flowchart LR
subgraph Sources
A[data/inbox] --> I
B[Public pages<br/>robots.txt, 1 req / 2s] --> I
C[Imgflip API] --> I
D[GIPHY API] --> I
E[AI templates] --> I
end
I[npm run ingest<br/>sha256 dedupe, WebP or GIF,<br/>annotate, embed] --> DB[(SQLite<br/>data/hanapmeme.db<br/>+ vectors)]
I --> CAT[catalog.json]
DB --> S[lib/search.ts<br/>cosine + rerank<br/>or BM25 fallback]
S --> W[Website]
S --> R[REST API]
S --> M[MCP /api/mcp]
T[(Vercel Blob<br/>takedowns)] -.filter.-> SPath | What it holds |
| Pages ( |
|
|
| Client components: search, gallery, modal, toast |
| SQLite access. Every read filters to |
| Embedding search, rerank, keyword fallback, synonym map |
| Image annotation with structured output |
| Captions and meme rendering with |
| MCP tools |
| Vercel Blob store for takedowns on a deploy |
|
|
| Local database and images (gitignored) |
How OpenAI is used
Job | Model | Where |
Annotate each image (Taglish and English description, text in the image, tags, who or what is in it, pop-culture references, why it is known, format, safety flags) |
|
|
Embed descriptions and queries |
|
|
Rerank the top 30 results (3 s timeout) |
|
|
Pick a template and write captions |
|
|
Template backgrounds |
|
|
Landing page stickers |
|
|
Model substitution: gpt-image-2 does not accept background: "transparent", so the three transparent landing stickers use gpt-image-1.5. All other model IDs match the spec. You can override each model with OPENAI_TEXT_MODEL, OPENAI_EMBED_MODEL, and OPENAI_IMAGE_MODEL.
Every AI call has a timeout and a fallback. If a call fails, search falls back to cosine order or keyword search, and the generator falls back to a plain caption.
Rough cost for 30 images: annotation uses about 1,500 input tokens and 400 output tokens per image at $2 and $10 per 1M tokens, so about $0.21. Embeddings cost less than $0.01. The 8 templates are a one-time cost of a few cents each.
REST API
Method | Path | Notes |
GET |
|
|
GET |
| Metadata and provenance |
GET |
| WebP or GIF bytes |
POST |
| Body |
POST |
| Body |
CORS is open for GET only. Each route has a rate limit per IP.
MCP
The server is at /api/mcp (stateless Streamable HTTP). It has three tools:
search_memes {query, limit?}returns, for each result, a text block with id, description, source credit, and rights status, and a WebP thumbnail of 512 px or less.get_meme {id}returns the full image and provenance.generate_meme {situation}returns the PNG and the caption text.
Results for scraped items include Rights unverified. Source: <url> · Report: <site>/takedown?id=<id>.
Connect Codex:
codex mcp add hanapmeme --url http://localhost:3000/api/mcpTest with the MCP Inspector:
npx @modelcontextprotocol/inspector
# Transport: Streamable HTTP, URL: http://localhost:3000/api/mcpDeploy to Vercel
The deploy bundles your local data/hanapmeme.db and data/memes/ (read-only). Takedowns on the live site go to a private Vercel Blob store, so a reported meme stays hidden after a cold start.
npx vercel link
npx vercel blob create-store hanapmeme-takedowns --access private --yes
npx vercel env add OPENAI_API_KEY production
npx vercel deploy --prod.vercelignore keeps .env*, data/inbox/, and sources.yaml out of the upload.
Production deploys come from the CLI only. vercel.json turns off automatic deploys from main, because a Git build has no meme library and would replace the live site with an empty one. Pull request previews still deploy, and they show the empty state.
If the Blob store is missing on a deploy, POST /api/report returns 503 and saves nothing. It never claims that it removed an image when it did not.
Demo script
Open
/searchand typelate na naman sa standup.In Codex, after
codex mcp add, ask: "Kuya, bigyan mo ako ng meme para sa standup na late na naman ako". Codex callssearch_memesand shows the same memes with credit.Click Report on one meme. Search again on the site, with
curl /api/search, and in Codex. The meme is gone in all three.
Who is in the meme
Each meme has three context fields: subjects (people, shows, or characters), references (shows, catchphrases, and trends), and context_note (why it is known in the Pinoy meme scene). Search, embeddings, the API, and MCP all use them, so a search for vice ganda, showtime, or malupiton finds memes that mention them.
The AI fills these fields from visible text, captions, watermarks, and the source title. It never identifies a real person from their face. To make a meme findable by name, add a maintainer note to its link in sources.yaml or to its inbox sidecar:
urls:
- url: https://media.tenor.com/<id>/example.gif
subjects: ["Malupiton"]
context: Pinoy vlogger known for the "boss" catchphraseAfter you change notes, or after an upgrade that adds fields, run npm run ingest -- --reannotate. It re-annotates stored memes from their saved files. A new review can turn safety flags on and exclude a meme, but it never turns a flag off or re-activates a meme.
Optional sources
sources.example.yamllists about 60 Tenor and GIPHY search pages for Pinoy topics across seasons (Pasko, 13th month pay, walang pasok), commute, money, food, family, love and hugot, showbiz, sports, gaming, and music. Each topic is capped at 5 images. Partisan politics is left out on purpose. Ingest runs these before the Imgflip API, so--limitfills with Philippine memes first. Each image's alt text and filename go to the AI as its source title.data/inbox/takes your own images. A sidecar<name>.jsoncan setsource_url,original_author,rights_status(ownorunverified), and descriptions.GIPHY: set
GIPHY_API_KEYin.env.local(free key at developers.giphy.com). Ingest then searches thegiphy.querieslist insources.yamland keeps GIFs animated.
Defaults chosen during the build
Images are stored in
data/memes/and served through an API route, not frompublic/memes/. The route checks the status, so removed images cannot leak by URL.Scraped page and GIPHY images are stored only after an AI safety review. With no key, ingest skips them.
Imgflip and inbox images with no key get no safety flags. Use the Report button to remove a bad one.
Ingest never re-activates an
excludedortakedownmeme, except throughapprove: true(see below).The maintainer can set
approve: trueon a link insources.yamlor in an inbox sidecar. Approval lifts only thepossible_minorandprivate_individualflags, neverexplicitorhateful, and never a takedown. Ingest logs each override. Read AGENTS.md for the rule.Report has no login, by design: anyone can hide a meme at once. The rate limit uses
x-vercel-forwarded-foron Vercel. On other hosts, put the app behind a proxy that setsX-Forwarded-For.catalog.jsonlists active memes only.The rate limit is in memory per server process.
Results show at most 2 memes of the same person or show before others, unless the query names that subject. Browsing with no query uses the same rule.
The site uses one dark theme.
Troubleshooting
Problem | Fix |
The search page shows "Wala pang memes" | Run |
Search mode is always | Make sure that |
| The site does not allow bots on that path. Remove it from |
| Run |
Ingest is slow | Each annotation is one reasoning call of 20 to 40 seconds. Use |
Credits
Built at DevDay Exchange Community: Manila, Nov 6, 2026. Anton font by The Anton Project Authors (SIL OFL 1.1). Templates from the Imgflip API. GIFs powered by GIPHY when enabled.
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
Related MCP Connectors
Find memes and Chinese 表情包, auto-place them into articles, or draw custom memes with AI.
Search 5,500+ meme & reaction video clips, preview them in chat, download clean HD/4K files.
Look up meme template images by name or description, with disambiguation for ambiguous names.
Bilingual dual memory with SSC for AI agents. Semantic search, embeddings, profiles.
Related MCP Servers
- AlicenseNot gradedqualityDmaintenanceA Model Context Protocol server for managing, searching, and retrieving local meme images. It automatically hosts memes via a built-in HTTP server to ensure images can be displayed within chat applications.1MIT
- AlicenseNot gradedqualityCmaintenanceEnables AI agents to create memes by selecting from a library of templates and rendering captions with proper typesetting.AGPL 3.0
- FlicenseAqualityDmaintenanceEnables AI assistants to semantically search a local Telegram meme collection using natural language queries, returning matching images with captions and file paths, and retrieving specific images by content hash.2-
- AlicenseAqualityBmaintenanceEnables users and coding agents to trade GIFs in chat, view animated GIFs frame by frame, and record reactions locally so agents can learn user preferences and send GIFs at fitting moments.7376 npmMIT