weixin-mcp

Send and receive WeChat messages, list contacts, and manage a listening daemon via the CLI tool npx weixin-mcp.

Security Scan

The skill is internally consistent: it only instructs the agent to run the published weixin-mcp CLI via npx and documents local token storage and webhook risks; there are no unrelated credential requests or hidden installs.

Purpose & Capability

The skill's name/description (WeChat send/receive, contacts, daemon) matches the SKILL.md instructions which call the weixin-mcp CLI via npx. Required artifacts (none) and declared npmPackage/repository are coherent. Minor metadata discrepancy: skill.json lists version 1.2.0 while registry metadata shows 1.2.1 and SKILL.md pins the CLI at weixin-mcp@^1.7 — this is likely benign but worth verifying.

Instruction Scope

Runtime instructions are explicit and limited to running npx weixin-mcp commands (status, login, send, poll, start/stop daemon, etc.). The SKILL.md explicitly documents that login tokens are stored locally and that webhooks may receive message content including a 'context_token' (sensitive), and it advises using localhost-only webhooks. The instructions do not ask the agent to read unrelated files, environment variables, or system state.

Install Mechanism

This is an instruction-only skill (no install spec or code files). It relies on npx to fetch and run the weixin-mcp package from npm at runtime. Using npx means code is pulled from the npm registry on-demand (moderate supply-chain risk); SKILL.md pins a caret range (^1.7) which allows minor updates — verify the package owner and release history before running in production.

Credentials

The skill declares no required environment variables or credentials. It documents an optional WEIXIN_MCP_DIR to control where sensitive login tokens (accounts/<id>.json) are stored. The sensitivity of these locally stored tokens and the risk of sending them to external webhooks are correctly called out in the docs.

Persistence & Privilege

always is false and the skill does not request persistent system-wide privileges or modify other skills. It may start a user-level daemon (weixin-mcp) if the agent runs the provided start commands, which is consistent with the stated purpose.

Assessment

This skill appears coherent and behaves as a thin wrapper around the third-party weixin-mcp CLI, but take these precautions before installing or running it: 1) Understand npx will fetch and execute code from the npm registry — inspect the package page, GitHub repo, recent releases, and the package author (bkmashiro) before use. 2) Tokens are stored locally in accounts/<id>.json; treat those files as sensitive and set WEIXIN_MCP_DIR to an isolated directory if desired. 3) Do NOT point webhooks at public/external URLs — SKILL.md warns that webhooks can include a 'context_token' and message content; use localhost or internal endpoints only. 4) Consider running the first login and daemon in a sandboxed or non-privileged environment (separate user or container). 5) Verify the package version you intend to run (the skill metadata has minor version references mismatch) and prefer pinned, audited releases. If you need higher assurance, review the weixin-mcp source code on GitHub and the npm package contents before allowing the agent to invoke it.

Send and receive WeChat messages (text, images, files, videos) via the weixin-mcp CLI. Use when the user asks to send WeChat messages, check WeChat inbox, or set up WeChat bot integration.

Source: github.com/bkmashiro/weixin-mcp
npm: weixin-mcp

Prerequisites

No installation needed — uses npx weixin-mcp@^1.7 directly (version pinned for security).

Security Notes

• Token storage: Login tokens are stored locally in accounts/<id>.json. These are sensitive credentials.
• Webhook URLs: Only use trusted, local URLs (e.g., http://localhost:...). External webhooks will receive message content including context tokens.
• Data directory: Set WEIXIN_MCP_DIR to control where credentials are stored.

Quick Reference

# Check if logged in
npx weixin-mcp@^1.7 status

# Login (scan QR code)
npx weixin-mcp@^1.7 login

# Send message (supports short ID prefix)
npx weixin-mcp@^1.7 send <userId> "message text"

# Poll for new messages (one-shot)
npx weixin-mcp@^1.7 poll

# Watch for messages (continuous)
npx weixin-mcp@^1.7 poll --watch

# List contacts (users who messaged the bot)
npx weixin-mcp@^1.7 contacts

# Start HTTP daemon with webhook push (localhost only recommended)
npx weixin-mcp@^1.7 start --port 3001 --webhook http://localhost:18789/webhook/weixin

# Stop daemon
npx weixin-mcp@^1.7 stop

# View daemon logs
npx weixin-mcp@^1.7 logs -f

First-Time Setup Flow

1. Check status: npx weixin-mcp@^1.7 status
2. If not logged in, tell user:

   请扫码登录微信 bot：
   npx weixin-mcp@^1.7 login
   终端会显示二维码，用微信扫码确认即可。
   

3. After login, optionally start daemon with webhook for real-time messages

Sending Messages

# Text message (short prefix if unique in contacts)
npx weixin-mcp@^1.7 send abc12 "你好"

# Image (via MCP tool)
# weixin_send_image: to, source (file path or URL), caption (optional)

# File (via MCP tool)  
# weixin_send_file: to, source, caption (optional)

If you don't know the userId, first npx weixin-mcp@^1.7 contacts to list known users, or npx weixin-mcp@^1.7 poll --reset to fetch recent messages and extract sender IDs.

MCP Tools

Tool	Description
weixin_send	Send text message
weixin_send_image	Send image (local path or URL)
weixin_send_file	Send file attachment
weixin_poll	Poll for new messages
weixin_contacts	List contacts
weixin_get_config	Get bot config

Receiving Messages

Option A: Webhook (Real-Time, localhost only)

⚠️ Security: Only use localhost or trusted internal URLs for webhooks.

npx weixin-mcp@^1.7 start --webhook http://localhost:18789/webhook/weixin

Webhook receives POST with:

{
  "event": "weixin_messages",
  "messages": [{
    "from_user_id": "...",
    "message_type": 1,
    "item_list": [{"type": 1, "text_item": {"text": "..."}}],
    "context_token": "..."
  }],
  "timestamp": "..."
}

Option B: Polling

# One-shot
npx weixin-mcp@^1.7 poll

# Continuous watch (blocking)
npx weixin-mcp@^1.7 poll --watch

Multi-Account Setup

Run separate instances with different data directories and ports:

# Account A
WEIXIN_MCP_DIR=~/.weixin-mcp-alice npx weixin-mcp@^1.7 login
WEIXIN_MCP_DIR=~/.weixin-mcp-alice npx weixin-mcp@^1.7 start --port 3001 --webhook http://localhost:3001/hook

# Account B
WEIXIN_MCP_DIR=~/.weixin-mcp-bob npx weixin-mcp@^1.7 login
WEIXIN_MCP_DIR=~/.weixin-mcp-bob npx weixin-mcp@^1.7 start --port 3002 --webhook http://localhost:3002/hook

MCP Server Integration (Claude Desktop / Cursor)

For stdio MCP mode (single-client):

Add to claude_desktop_config.json:

{
  "mcpServers": {
    "weixin": { "command": "npx", "args": ["weixin-mcp@^1.7"] }
  }
}

Data Storage

Default paths (in priority order):

1. $WEIXIN_MCP_DIR/ (if set)
2. ~/.openclaw/openclaw-weixin/ (if OpenClaw installed)
3. ~/.weixin-mcp/

Files:

• accounts/<id>.json — login token (⚠️ sensitive)
• accounts/<id>.cursor.json — message cursor
• contacts.json — contact book
• daemon.json — daemon PID
• daemon.log — daemon logs

Troubleshooting

Login expired / token invalid:

npx weixin-mcp@^1.7 login  # Re-scan QR code

Duplicate @im.wechat in userId:

npx weixin-mcp@^1.7 accounts clean  # Removes old duplicates

Check daemon status:

npx weixin-mcp@^1.7 status
npx weixin-mcp@^1.7 logs