Skip to main content
Glama

yelin-sticker-mcp

中文 | English


中文

一个 stdio MCP 服务:让 AI 助手按"想表达的意思"找表情包、发表情包,还能把聊天里收到的图收进你自己的表情库。 走标准输入输出,不开网络服务;除非你配置了 webhook 或运行下载脚本,否则不联网。

仓库里不带任何图片。图从哪来见下面的导入自己的表情和动态 Emoji。

先看你需要哪个

  • 你的聊天窗会显示工具结果里的图片(有的 MCP 聊天客户端会,比如 Kelivo;能接 MCP 不等于会显示,以你用的版本为准):只装这一个就够了。AI 用 sticker_send 发表情时,图放在工具结果里,由聊天窗显示。动图会不会动、显示多大,由客户端决定。

  • 你的聊天窗不显示工具图片,或者表情要送到另一个页面(比如 AI 在服务器上跑,你在自己做的网页或 App 里聊天):有两种做法。一是用本插头自带的 webhook(格式见下面"webhook 收到什么");二是再装同一个作者写的 yelin-send-mcp,它还能发 AI 自己画的图、写的歌和文件,examples/ 里有收件端例子。不管哪种,收到以后都要自己接进页面显示;用 yelin-send-mcp 转发时,它要能读到这里给出的图片路径。

  • 在手机上用:本插头走 stdio,要在电脑或服务器上运行。只能连远程 MCP 的客户端,需要一个兼容的网关,并按该客户端的要求配置传输方式、HTTPS 和认证。

工具

工具

做什么

sticker_find(want, n?)

按意思找候选(如"抱抱""晚安""委屈""thumbs up")。回 id、分类、名字、文件路径,前几张附缩略预览。只找不发。

sticker_send(id, text?)

发出挑好的表情,可带一句话。默认把表情原图放在工具结果里(3 MiB 以内的 PNG/GIF/JPEG/WEBP;超过上限、格式认不出或读不了时,换成第一帧静态预览),能显示工具图片的客户端会显示它;配置了 STICKER_WEBHOOK_URL 才 POST 出去。

sticker_save(path, tags)

把一张本地图片(比如聊天里收到的表情)连同标签收进"自己的"库,按内容去重。

sticker_untagged(n?)

把导入后还没起名的图拼成一张编号的 6×6 总表(每格左上角是编号),附"编号→id"对照。

sticker_tag(id, tags) / sticker_tag(batch=...)

起名/改标签(覆盖旧标签)。id 可以写最近一张总表上的编号;batch 一行一张"编号 标签…",一次起完。

搜索打分:在"分类 + 名字 + 关键词"上做 BM25。中文拆成单字和相邻两字词(单字权重低),英文按词。名字完全一致的最靠前,名字/关键词包含查询词的其次;"自己的"库加权 ×1.5。多字查询只撞上单个字(比如搜"晚安"碰上"安全")不算命中。索引缓存在状态目录,图库或标签有变化会自动重建。

安装

需要 Python 3.10 或更新。

git clone <本仓库地址> yelin-sticker-mcp
cd yelin-sticker-mcp
python3 -m venv .venv
.venv/bin/pip install -r requirements.txt
.venv/bin/python sticker_mcp.py paths     # 看看各个目录最终落在哪

配到 Claude Code

claude mcp add --transport stdio sticker -- \
  /path/to/yelin-sticker-mcp/.venv/bin/python /path/to/yelin-sticker-mcp/sticker_mcp.py

带环境变量(--env 放在服务名前面):

claude mcp add --transport stdio \
  --env STICKER_HOME="$HOME/stickers" \
  --env STICKER_WEBHOOK_URL=https://example.com/hooks/sticker \
  --env STICKER_WEBHOOK_TOKEN=your-token-here \
  sticker -- /path/to/yelin-sticker-mcp/.venv/bin/python /path/to/yelin-sticker-mcp/sticker_mcp.py

加完在 Claude Code 里用 /mcp 看连上没有;删掉用 claude mcp remove sticker。 其他支持 MCP 的客户端,一般是这样的 JSON:

{
  "mcpServers": {
    "sticker": {
      "command": "/path/to/yelin-sticker-mcp/.venv/bin/python",
      "args": ["/path/to/yelin-sticker-mcp/sticker_mcp.py"],
      "env": { "STICKER_HOME": "~/stickers" }
    }
  }
}

环境变量与配置文件

优先级:环境变量 > 配置文件 > 默认值。配置文件是 JSON,格式见 config.example.json;路径可以用 ~。

环境变量

配置文件键

默认值

说明

STICKER_CONFIG

—

~/.config/yelin-sticker-mcp/config.json(遵循 XDG_CONFIG_HOME)

配置文件位置

STICKER_HOME

home

~/.local/share/yelin-sticker-mcp(遵循 XDG_DATA_HOME)

下面各目录的默认根

STICKER_LIBRARY_DIR

library_dir

$STICKER_HOME/library

图库:一级子目录名 = 分类,文件名 = 描述

STICKER_MINE_DIR

mine_dir

$STICKER_HOME/mine

"自己的"库(图片 + tags.json),搜索时优先

STICKER_NOTO_DIR

noto_dir

$STICKER_HOME/noto

build_noto.py 下载的动态 Emoji

STICKER_THUMBS_DIR

thumbs_dir

$STICKER_HOME/thumbs

160px webp 缩略图

STICKER_STATE_DIR

state_dir

$STICKER_HOME/state

索引缓存、编号总表、发送记录 sent.jsonl

STICKER_WEBHOOK_URL

webhook_url

空

设了才往外发(必须是 https://)

STICKER_WEBHOOK_TOKEN

不支持

空

webhook 令牌,只从环境变量读,不写进配置文件

STICKER_WEBHOOK_HEADER

webhook_header

Authorization

令牌放在哪个请求头;是 Authorization 时自动加 Bearer 前缀,其他头原样放

STICKER_WEBHOOK_EMBED

webhook_embed

关

1/true:把图片 base64 一起发(接收方不在本机时用)

STICKER_WEBHOOK_ALLOW_HTTP

webhook_allow_http

关

1/true:放行 http:// 地址,只给本机调试用(令牌会明文发出)

webhook 收到什么

sticker_send 在配置了 STICKER_WEBHOOK_URL 时发一个 POST,Content-Type: application/json:

{
  "event": "sticker",
  "ts": "2026-01-01T12:00:00+00:00",
  "id": "n1a2b3c4d5",
  "kind": "noto",
  "category": "动态·亲亲爱你",
  "name": "抱抱",
  "char": "🤗",
  "path": "/本机/上的/原图路径.webp",
  "thumb": "/本机/上的/缩略图.webp",
  "text": "随表情一起说的话",
  "mime": "image/webp",
  "data": "<base64,只在 STICKER_WEBHOOK_EMBED 打开时有>"
}

返回任何 2xx 都算成功;4xx/5xx 或连不上会作为工具错误返回给助手。kind 是 library、noto 或 mine。

不跟随重定向:webhook 返回 3xx 一律当失败,不重发、不带令牌去 Location 指的地址(不管是别的域名还是从 https 降到 http)。请把 STICKER_WEBHOOK_URL 直接填成最终地址。

导入自己的表情

  1. 直接放进图库:library/<分类>/<描述>.gif。文件名就是搜索用的描述,一级目录名是分类(开头的数字序号会去掉,01_开心 → 开心);更深的子目录名也会当关键词。以 . 开头的文件和目录会跳过。放进去下次搜索就会自动重建索引。

  2. 一次导一批,让助手看图起名:

    .venv/bin/python sticker_mcp.py import ~/Pictures/stickers  more.gif

    图片进"自己的"库,标签先空着(按文件头认 PNG/JPG/GIF/WEBP,按内容哈希去重,打不开的会撤回,HEIC 请先转成 JPG/PNG)。然后在对话里让助手调 sticker_untagged 看编号总表,再用 sticker_tag(batch="1 抱抱 撒娇\n2 晚安 困了") 一次起完。没起名的图不会出现在搜索结果里。

  3. 聊天里收到的图:让助手用 sticker_save(path, tags) 收进"自己的"库。

动态 Emoji(可选)

想要会动的 Emoji,自己运行下载脚本(从官方地址下载到你本机,约 600 个,约 250MB;已下载的会跳过,可以随时重跑补缺):

.venv/bin/python build_noto.py              # 下载到 STICKER_NOTO_DIR;也可以 --dir 指定
.venv/bin/python make_thumbs.py --all       # 可选:提前把缩略图都做好

脚本下载谷歌 Noto Emoji Animation 的官方 512px 动态 webp(不收肤色变体),同时用 Unicode CLDR 的中文注释生成中文名和关键词,补了一些聊天常用叫法("晚安""比心""么么哒"等),并按 Unicode 子分组归成十几个中文大类,写成 catalog.json;同目录会写 ATTRIBUTION.txt(逐个文件写明出处和许可)和 LICENSE-UNICODE.txt(Unicode License v3 的完整版权与许可告示,随 Unicode 数据一起保留)。

测试

.venv/bin/pip install pytest
.venv/bin/python -m pytest -q

测试全部在临时目录里跑,不碰你真实的图库和配置,也不联网(webhook 走 urllib 真实的处理链,只把最底层的 http/https 收发换成假的,重定向也在里面测)。

出处与许可


Related MCP server: pwa-sticker-mcp

English

A stdio MCP server that lets an AI assistant find stickers by what it wants to express, send them, and keep a personal sticker library built from images it receives in chat. It talks over stdin/stdout and opens no network service; it only goes online if you configure a webhook or run the download script.

No images ship with this repository. See Importing your own stickers and Animated emoji.

Which one do you need

  • Your chat window shows images from tool results (some MCP chat clients do, Kelivo for example; speaking MCP does not mean it shows them, so check the version you use): this plug alone is enough. When the AI calls sticker_send, the image is in the tool result and the chat window shows it. Whether animations play, and how big it looks, is up to the client.

  • Your chat window does not show tool images, or stickers have to reach another page (say the AI runs on a server and you chat in your own web page or app): two ways. Use this plug's own webhook (its JSON payload is shown under "webhook 收到什么" in the Chinese section; the field names are English), or also install yelin-send-mcp (same author), which can send pictures the AI made, songs and files too, and whose examples/ has receivers. Either way you still wire what arrives into your page; when yelin-send-mcp forwards a sticker it must be able to read the image path this plug returns.

  • On a phone: this plug speaks stdio and runs on a computer or a server. Clients that only take remote MCP servers need a compatible gateway set up the way that client requires (transport, HTTPS, authentication).

Tools

Tool

What it does

sticker_find(want, n?)

Find candidates by meaning ("抱抱", "晚安", "thumbs up"...). Returns id, category, name, file path, with previews of the first few. Search only.

sticker_send(id, text?)

Send a picked sticker, optionally with a line of text. By default the tool result carries the sticker itself (PNG/GIF/JPEG/WEBP up to 3 MiB; over the cap, in another format or unreadable, a still first-frame preview instead), which clients that show tool images can show; it POSTs only when STICKER_WEBHOOK_URL is set.

sticker_save(path, tags)

Copy a local image (e.g. a sticker received in chat) into your own library with tags; deduplicated by content.

sticker_untagged(n?)

Render imported-but-untagged images as a numbered 6x6 contact sheet, with a number -> id map.

sticker_tag(id, tags) / sticker_tag(batch=...)

Set tags (replaces old ones). id may be a number from the latest sheet; batch is one "number tags" per line.

Ranking: BM25 over "category + name + keywords". Chinese text is split into single characters (low weight) and two-character words; latin text into words. Exact name matches rank first, names/keywords containing the query next; your own library gets a x1.5 boost. A multi-character query that only shares single characters with a sticker (e.g. "晚安" vs "安全") is not a match. The index is cached and rebuilt automatically when files or tags change.

Install

Python 3.10+.

git clone <this repository> yelin-sticker-mcp
cd yelin-sticker-mcp
python3 -m venv .venv
.venv/bin/pip install -r requirements.txt
.venv/bin/python sticker_mcp.py paths     # show the resolved directories

Use with Claude Code

claude mcp add --transport stdio sticker -- \
  /path/to/yelin-sticker-mcp/.venv/bin/python /path/to/yelin-sticker-mcp/sticker_mcp.py

With environment variables (--env goes before the server name):

claude mcp add --transport stdio \
  --env STICKER_HOME="$HOME/stickers" \
  --env STICKER_WEBHOOK_URL=https://example.com/hooks/sticker \
  --env STICKER_WEBHOOK_TOKEN=your-token-here \
  sticker -- /path/to/yelin-sticker-mcp/.venv/bin/python /path/to/yelin-sticker-mcp/sticker_mcp.py

Check it with /mcp inside Claude Code; remove it with claude mcp remove sticker. Other MCP clients usually take the same command / args / env JSON shown in the Chinese section above.

Environment variables and config file

Precedence: environment > config file > defaults. The config file is JSON (see config.example.json); ~ is expanded.

Variable

Config key

Default

Meaning

STICKER_CONFIG

—

~/.config/yelin-sticker-mcp/config.json (honours XDG_CONFIG_HOME)

config file location

STICKER_HOME

home

~/.local/share/yelin-sticker-mcp (honours XDG_DATA_HOME)

default root of the folders below

STICKER_LIBRARY_DIR

library_dir

$STICKER_HOME/library

image library: top-level folder = category, file name = description

STICKER_MINE_DIR

mine_dir

$STICKER_HOME/mine

your own library (images + tags.json), ranked first

STICKER_NOTO_DIR

noto_dir

$STICKER_HOME/noto

animated emoji downloaded by build_noto.py

STICKER_THUMBS_DIR

thumbs_dir

$STICKER_HOME/thumbs

160px webp thumbnails

STICKER_STATE_DIR

state_dir

$STICKER_HOME/state

index cache, contact sheets, send log sent.jsonl

STICKER_WEBHOOK_URL

webhook_url

empty

POST target; nothing is sent unless set (must be https://)

STICKER_WEBHOOK_TOKEN

not supported

empty

webhook token, environment only, never read from the config file

STICKER_WEBHOOK_HEADER

webhook_header

Authorization

header carrying the token; Authorization gets a Bearer prefix, other headers get the raw value

STICKER_WEBHOOK_EMBED

webhook_embed

off

1/true: include the image as base64 (for receivers on another machine)

STICKER_WEBHOOK_ALLOW_HTTP

webhook_allow_http

off

1/true: accept an http:// URL, for local debugging only (the token is sent in clear text)

The webhook body is the JSON shown in the Chinese section (event, ts, id, kind, category, name, char, path, thumb, text, plus mime/data when embedding). Any 2xx response counts as success; errors are returned to the assistant as tool errors.

Redirects are never followed: any 3xx is a failure. The request is not retried and the token is never sent to the Location target (another host, or https downgraded to http). Set STICKER_WEBHOOK_URL to the final address.

Importing your own stickers

  1. Drop files into the library: library/<category>/<description>.gif. The file name is the searchable description and the top-level folder is the category (a leading number like 01_ is stripped); deeper folder names become keywords. Dot-files and dot-folders are skipped. The index rebuilds on the next search.

  2. Import a batch and let the assistant name them:

    .venv/bin/python sticker_mcp.py import ~/Pictures/stickers more.gif

    Images go into your own library untagged (format detected from the file header: PNG/JPG/GIF/WEBP; deduplicated by content; unreadable files are rolled back; convert HEIC first). Then ask the assistant to call sticker_untagged and name them with sticker_tag(batch=...). Untagged images never show up in search.

  3. Images received in chat: the assistant saves them with sticker_save(path, tags).

Animated emoji (optional)

Run the download script yourself (it fetches from the official sources to your machine: about 600 files, ~250 MB; files already present are skipped, so it is safe to re-run):

.venv/bin/python build_noto.py              # into STICKER_NOTO_DIR, or pass --dir
.venv/bin/python make_thumbs.py --all       # optional: pre-build thumbnails

It downloads the official 512px animated webp files of Google's Noto Emoji Animation (skin-tone variants skipped), builds Chinese names and keywords from the Unicode CLDR zh annotations plus a few everyday chat aliases, groups emoji into about 15 Chinese categories from the Unicode subgroups, and writes catalog.json, an ATTRIBUTION.txt (source and license of every file) and LICENSE-UNICODE.txt (the full Unicode License v3 copyright and permission notice, which has to stay with the Unicode data).

Tests

.venv/bin/pip install pytest
.venv/bin/python -m pytest -q

Tests run in temporary directories only: no real library, no real config, no network (the webhook goes through urllib's real handler chain with only the bottom http/https layer faked, redirects included).

Credits and licenses

  • Code in this repository: MIT, see LICENSE.

  • No sticker images are included.

  • Animated emoji: Noto Emoji Animation by Google, licensed under CC BY 4.0 (https://googlefonts.github.io/noto-emoji-animation/, https://creativecommons.org/licenses/by/4.0/). build_noto.py downloads them from the official source to your machine; keep the attribution if you redistribute them.

  • Chinese names and keywords: Unicode CLDR annotations; categories from Unicode emoji-test.txt. © Unicode, Inc., licensed under the Unicode License v3 (https://github.com/unicode-org/cldr, https://www.unicode.org/license.txt). build_noto.py writes the full notice to LICENSE-UNICODE.txt in the download folder; the MIT license of this repository does not cover the downloaded data.

  • Images you add to the library or your own collection belong to their respective rights holders; only add images you are allowed to use.

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    Related MCP Connectors

    Related MCP Servers