Skip to content
Back to search

wechat-mcp

MCP server for your own personal WeChat account: drives the official WeChat for Linux client in a container (AT-SPI + X11), Streamable HTTP, deployable on Railway

Safety scan

A static text scan, not a guarantee. Select the badge to see what was scanned and every finding.

Badge for your README
findsafeskills safety rating

Markdown

[![findsafeskills safety rating](/api/listings/zongwei-tang--wechat-mcp/badge.svg)](/listings/zongwei-tang--wechat-mcp)

HTML

<a href="/listings/zongwei-tang--wechat-mcp"><img src="/api/listings/zongwei-tang--wechat-mcp/badge.svg" alt="findsafeskills safety rating" /></a>

Install

i

What was scanned

The files the safety scan read, as written by the repository's author and shown as plain text. Lines with a finding are marked.

README.md · README · 86 lines
  1. # wechat-mcp
  2. **English** | [简体中文](README.zh-CN.md)
  3. An MCP server (Streamable HTTP) for **your own personal WeChat account**. It runs in a Linux container (Railway or any cloud host) — no Mac or Windows machine needed.
  4. > Not affiliated with Tencent. Use it only with your own account.
  5. ## How it works
  6. The container runs the **official WeChat for Linux** client (the latest build is downloaded from Tencent's CDN at image build time) on a virtual X display (Xvfb):
  7. - **Reading** — the AT-SPI accessibility tree (the interface screen readers use) exposes the chat list, messages, contacts, group members and profile cards.
  8. - **Acting** — simulated X11 keyboard/mouse input plus the clipboard send text, images and files, and drive quote-replies, forwarding and context menus.
  9. - **Group senders** — message rows do not expose the sender, so the server clicks the avatar once, reads the profile card, and caches the name by avatar image.
  10. - **No protocol emulation, no process injection, no database decryption** — it is the genuine client, operated the way a person would operate WeChat on a remote desktop.
  11. ### Limitations
  12. - The Linux client shares the "desktop" login slot with WeChat for Mac/Windows; logging in on one signs the other out.
  13. - Only messages the client has received since it logged in are readable. For older history use `wechat_import_history_from_phone` (WeChat's official "import chat history from phone").
  14. - Settings that are drawn on screen but not exposed to accessibility (group announcement, renaming a group, …) are not implemented.
  15. - Everything goes through one GUI, so calls run one at a time; a typical call takes 2–10 seconds.
  16. ## Login and keep-alive
  17. - First login: open `/login/<token>` (the QR code refreshes every 2.5 s), scan it with phone WeChat and confirm on the phone — or call the `wechat_login` tool to get the QR image.
  18. - The login profile lives on the `/data` volume, so restarts and redeploys do not need a new QR scan.
  19. - A background watcher checks every 30 s. If the client drops back to the "Log in / Enter WeChat" screen it clicks the button so your phone gets a confirmation prompt, retrying with back-off (10 min, 30 min, 1.5 h, then every 4 h) so an absent phone is not spammed.
  20. - If the phone's confirmation screen offers "auto-login on this device", turning it on avoids future confirmations.
  21. - After login the server turns off notification sounds (they destabilise headless clients) and turns on voice-message-to-text.
  22. - `/profile-export/<token>` and `/profile-import/<token>` move a logged-in device to another server.
  23. ## Endpoints
  24. | Path | Purpose |
  25. |---|---|
  26. | `/mcp/<token>` | Streamable HTTP MCP endpoint |
  27. | `/login/<token>` | Login page (live QR code, phone-confirmation status) |
  28. | `/profile-export/<token>` · `/profile-import/<token>` | Export / import the login profile (tar.gz) |
  29. | `/health` | Health check |
  30. `<token>` is the `MCP_AUTH_TOKEN` environment variable (if unset, one is generated and stored in `/data/mcp_token`).
  31. ## Deploy on Railway
  32. 1. Create a service that builds from this repository's Dockerfile.
  33. 2. Attach a volume at `/data` (required — otherwise every deploy needs a new login).
  34. 3. Set `MCP_AUTH_TOKEN` to a long random string. Optional: `PUBLIC_URL`, `LOGIN_WATCH_SECONDS`.
  35. 4. Generate a public domain and open `https://<domain>/login/<token>` to scan the QR code.
  36. 5. Add a custom connector in Claude: `https://<domain>/mcp/<token>`.
  37. Recommended: 2 GB RAM or more. Tip: restrict deploy triggers to code paths (`wechat_mcp/**`, `Dockerfile`, `docker/**`, `requirements.txt`) — every redeploy restarts WeChat and asks your phone to confirm.
  38. Run locally:
  39. ```bash
  40. docker build -t wechat-mcp .
  41. docker run -d --shm-size=1g -p 8000:8000 -e MCP_AUTH_TOKEN=change-me -v wechat-data:/data wechat-mcp
  42. ```
  43. ## Tools (65)
  44. **Account**: `wechat_status` `wechat_login` `wechat_logout` `wechat_restart_client` `wechat_my_profile` `wechat_get_settings` `wechat_set_setting`
  45. **Chats**: `wechat_list_chats` `wechat_unread_chats` `wechat_current_chat` `wechat_open_chat` `wechat_search` `wechat_find_chat` `wechat_chat_options` `wechat_chat_action` `wechat_pin_chat` `wechat_mute_chat` `wechat_mark_unread` `wechat_mark_read` `wechat_hide_chat` `wechat_delete_chat` `wechat_import_history_from_phone`
  46. **Reading**: `wechat_read_messages` `wechat_read_current_chat` `wechat_read_unread` `wechat_wait_for_message` `wechat_view_message` `wechat_open_image` `wechat_chat_screenshot` `wechat_search_chat_history` `wechat_copy_message`
  47. **Sending**: `wechat_send_message` (with @mentions / @all) `wechat_send_messages` `wechat_broadcast` `wechat_reply` (quote-reply) `wechat_send_image` `wechat_send_file` `wechat_send_files` `wechat_forward_message` `wechat_recall_message` `wechat_delete_message`
  48. **Message menu**: `wechat_message_options` `wechat_message_action` `wechat_favorite_message` `wechat_translate_message` `wechat_voice_to_text`
  49. **Contacts & groups**: `wechat_list_contacts` `wechat_contacts_with_remarks` `wechat_contact_info` `wechat_group_members` `wechat_group_member_info` `wechat_group_info` `wechat_friend_requests` `wechat_accept_friend_request` `wechat_add_friend` `wechat_create_group`
  50. **Favorites / Moments**: `wechat_list_favorites` `wechat_moments`
  51. **Low-level fallbacks**: `wechat_screenshot` `wechat_ui_tree` `wechat_click_element` `wechat_click` `wechat_press_key` `wechat_type_text` `wechat_scroll`
  52. ## Risks
  53. This automates your own account, and Tencent may apply risk controls to unusual behaviour. Avoid high-volume broadcasting; data-centre IPs can also trigger extra verification.
  54. ## License
  55. MIT

Ratings and comments

Sign in to rate this skill.

Sign in

Free to use. If it’s helped, pass it on.