Language: English | 简体中文

💡 Why This Project?

The official and community MCP solutions for SnowLuma (such as @snowluma/mcp) primarily target desktop environments (Claude Desktop, Cline, DSH) using local stdio process pipes.

However, when running AI agents on mobile devices (e.g. RikkaHub on Android) or remote cloud containers, clients cannot spawn local processes inside your server. They require a Remote MCP endpoint (Streamable HTTP / SSE) over public HTTPS.

Instead of wrapping bloated subprocess gateways like supergateway (which suffer from process stalls, high memory consumption, and zombie pipes during mobile network switches), SnowLuma Remote MCP provides an ultra-lightweight, native Python + FastMCP server.

Key Highlights

• 🚀 Native Remote Architecture: Pure asynchronous ASGI service, zero subprocess wrappers, zero pipe stalls.
• 🪶 Extremely Lightweight: Built on Python 3.12 + official mcp SDK; resident memory is only ~15 MB (vs 100MB+ for Node.js suites).
• 💬 Tailored for AI Agents: Flat, intuitive tooling for messaging, chat history retrieval, smart forward message unpacking, media placeholders that tell images from stickers, on-demand image viewing, group management, and quotation replies (21 tools).
• ✨ Full 280+ QQ System Reaction Support: Built-in 345+ popular Chinese aliases & network memes directly mapped to Linux NTQQ official Reaction IDs, plus full integer ID passthrough.
• 🛡️ Hardened Production Security: Bearer Token authentication, DNS-rebinding protection bypass for reverse proxies, and single-port HTTPS multiplexing.
• ⚡ Universal OneBot Pass-through: Includes call_onebot_action to access all 170+ native OneBot v11 actions without writing extra code.

🏗️ Architecture

flowchart TD
    Client["📱 Mobile Client (Android RikkaHub)"] -->|"HTTPS POST + Bearer Token<br/>(Streamable HTTP: /mcp)"| Nginx["🌐 Nginx (Reverse Proxy)"]
    Nginx -->|"HTTP (127.0.0.1:8766)"| MCP["⚡ SnowLuma Remote MCP Server (FastMCP ASGI)<br/>• BearerAuthMiddleware<br/>• 21 Standard Agent Tools<br/>• 280+ Official Reactions & 345+ Meme Map"]
    MCP -->|"HTTP POST (127.0.0.1:3000)"| SnowLuma["🐧 SnowLuma Runtime (Linux NTQQ + OneBot v11)"]

🛠️ Tool Catalog (21 Tools)

1. Messaging & Interaction

2. Group & Profile Management

3. Escape Hatch

About view_image: it is opt-in, never called automatically, and costly by nature — the picture lands in the client session and gets re-sent on every following turn. History placeholders already tell you what is there ([图片] image, [动画表情] animated sticker, [表情包:name] QQ market sticker) and 同#N marks a repeat of the same file, so only call it when the actual pixels matter. GIFs return their first frame; images older than QQ's media retention window return file has expired and cannot be recovered. Requires Pillow (see requirements.txt).

🚀 Quick Start

1. Clone & Install

git clone https://github.com/MorphieEndless/snowluma-remote-mcp.git
cd snowluma-remote-mcp

# Create virtual environment
python3 -m venv venv
source venv/bin/activate

# Install dependencies
pip install -r requirements.txt

2. Configure Environment

cp .env.example .env

Edit .env:\

MCP_HOST=127.0.0.1
MCP_PORT=8766
MCP_AUTH_TOKEN=generate_a_secure_token_here

SNOWLUMA_API_BASE=http://127.0.0.1:3000
SNOWLUMA_API_TOKEN=your_snowluma_onebot_token_here
SNOWLUMA_TIMEOUT=30.0

# Optional — view_image tuning (defaults shown)
# VIEW_IMAGE_ENABLED=1
# VIEW_IMAGE_MAX_EDGE=1024
# VIEW_IMAGE_TARGET_BYTES=204800
# VIEW_IMAGE_MAX_SOURCE_BYTES=20971520
# VIEW_IMAGE_CACHE_BYTES=67108864

3. Run

python server.py

Health check:\

curl http://127.0.0.1:8766/health

🌐 Production Deployment

Systemd Daemon

sudo cp systemd/snowluma-mcp.service /etc/systemd/system/
sudo systemctl daemon-reload
sudo systemctl enable --now snowluma-mcp.service

Nginx Reverse Proxy

Add the following locations into your HTTPS server block:\

# Remote MCP Endpoint
location /mcp {
    proxy_pass http://127.0.0.1:8766/mcp;
    proxy_http_version 1.1;
    proxy_set_header Host $host;
    proxy_set_header X-Real-IP $remote_addr;
    proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
    proxy_set_header X-Forwarded-Proto $scheme;

    # Disable buffering for streamable transport
    proxy_buffering off;
    proxy_cache off;
    chunked_transfer_encoding on;
    proxy_read_timeout 3600s;
    proxy_send_timeout 3600s;
}

# Health Probe (Exempt from auth)
location /mcp-health {
    proxy_pass http://127.0.0.1:8766/health;
    proxy_http_version 1.1;
    proxy_set_header Host $host;
    proxy_set_header X-Real-IP $remote_addr;
    proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
    proxy_set_header X-Forwarded-Proto $scheme;
}

📱 Connecting with RikkaHub (Android)

In RikkaHub:

1. Navigate to Settings → MCP → Add (+)
2. Select Streamable HTTP protocol
3. Fill in:
   • Name: SnowLuma
   • URL: https://your-domain.com/mcp
   • Authorization: Bearer <your_MCP_AUTH_TOKEN>
4. Save and verify that your tools appear in your Agent's tool palette (21 tools)! RikkaHub forwards tool-result images straight to the model, and falls back to OCR for text-only models.

🎭 Reaction Emojis Cheat Sheet (280+ Supported)

When calling set_msg_emoji_like, you can pass either the Chinese Name, Meme Alias, or the Numeric ID:

Categorized Popular Picks

• Approval & Praise (认同赞美):
  • 点赞 / 赞 (76), 超级赞 (364), 666 (356), 强 (76), OK / 好的 (124), 收到 (428), 鼓掌 (99), 崇拜 (318)
• Affection & Warmth (喜爱亲昵):
  • 贴贴 / 蹭蹭 (350), 比心 (319), 爱心 / 红心 (66), 抱抱 (49), 亲亲 (109), 蹭一蹭 (242), 么么哒 (410)
• Fun & Memes (幽默搞怪):
  • 狗头 / 汪汪 (277), 菜狗 / 菜汪 (317), 打call (311), 摸鱼 (285), 尊嘟假嘟 (354), 喵喵 (307), 摇起来 (413)
• Shock & Banter (震惊吐槽):
  • 吃瓜 (271), 问号脸 / 疑惑 (268), 托腮 (212), 辣眼睛 (265), 不是吧 (476), 给你一拳 (474), 裂开 (357), 大怨种 (344)
• Mood & Empathy (情绪状态):
  • 笑哭 (182), 坏笑 (101), 微笑 (14), 大哭 (9), 流泪 (5), 委屈 (106), 捂脸 (264), emo (382), 头秃 (267)

(Call list_supported_emojis tool at any time to get the complete dictionary of all 345+ aliases and 280+ system IDs).

📄 License

Distributed under the MIT License.