wechat-mcp
Operates your own personal WeChat account through the official Linux desktop client on a virtual display, providing 65 tools covering chats, messaging, contacts, groups, favorites, and Moments. Supports reading chats and unread messages, waiting for new messages, searching chat history, sending text (with @mentions/@all), images, and files, quote-replies, forwarding, recalling and deleting messages, translation and voice-to-text, message favoriting, managing chats (open, pin, mute, mark read/unread, hide, delete, import history from phone), listing contacts and group members, handling friend requests, adding friends, creating groups, plus low-level screenshot/UI-tree/click/type/scroll fallbacks.
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.
wechat-mcp
English | 简体中文
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.
Not affiliated with Tencent. Use it only with your own account.
How it works
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):
Reading — the AT-SPI accessibility tree (the interface screen readers use) exposes the chat list, messages, contacts, group members and profile cards.
Acting — simulated X11 keyboard/mouse input plus the clipboard send text, images and files, and drive quote-replies, forwarding and context menus.
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.
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.
Limitations
The Linux client shares the "desktop" login slot with WeChat for Mac/Windows; logging in on one signs the other out.
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").Settings that are drawn on screen but not exposed to accessibility (group announcement, renaming a group, …) are not implemented.
Everything goes through one GUI, so calls run one at a time; a typical call takes 2–10 seconds.
Related MCP server: WeChat FastBridge
Login and keep-alive
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 thewechat_logintool to get the QR image.The login profile lives on the
/datavolume, so restarts and redeploys do not need a new QR scan.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.
If the phone's confirmation screen offers "auto-login on this device", turning it on avoids future confirmations.
After login the server turns off notification sounds (they destabilise headless clients) and turns on voice-message-to-text.
/profile-export/<token>and/profile-import/<token>move a logged-in device to another server.
Endpoints
Path | Purpose |
| Streamable HTTP MCP endpoint |
| Login page (live QR code, phone-confirmation status) |
| Export / import the login profile (tar.gz) |
| Health check |
<token> is the MCP_AUTH_TOKEN environment variable (if unset, one is generated and stored in /data/mcp_token).
Deploy on Railway
Create a service that builds from this repository's Dockerfile.
Attach a volume at
/data(required — otherwise every deploy needs a new login).Set
MCP_AUTH_TOKENto a long random string. Optional:PUBLIC_URL,LOGIN_WATCH_SECONDS.Generate a public domain and open
https://<domain>/login/<token>to scan the QR code.Add a custom connector in Claude:
https://<domain>/mcp/<token>.
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.
Run locally:
docker build -t wechat-mcp .
docker run -d --shm-size=1g -p 8000:8000 -e MCP_AUTH_TOKEN=change-me -v wechat-data:/data wechat-mcpTools (65)
Account: wechat_status wechat_login wechat_logout wechat_restart_client wechat_my_profile wechat_get_settings wechat_set_setting
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
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
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
Message menu: wechat_message_options wechat_message_action wechat_favorite_message wechat_translate_message wechat_voice_to_text
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
Favorites / Moments: wechat_list_favorites wechat_moments
Low-level fallbacks: wechat_screenshot wechat_ui_tree wechat_click_element wechat_click wechat_press_key wechat_type_text wechat_scroll
Risks
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.
License
MIT
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
This server cannot be deployed
Maintenance
Related MCP Connectors
Hosted WhatsApp MCP server: read, search and reply to your own WhatsApp chats from your AI.
Hosted WhatsApp MCP server: send and read messages from your own linked number. OAuth sign-in.
Drive WhatsApp from any MCP client: pair devices, send text and media, manage contacts and groups.
Your own WhatsApp as an MCP server: read, search and send from any MCP client.
Related MCP Servers
- FlicenseNot gradedqualityCmaintenanceEnables AI applications to send and read WeChat messages on Windows PCs through QR code authentication. Provides message polling, text sending, and session persistence for AI-powered chat interactions.43 npm1-
- AlicenseCqualityCmaintenanceLocal macOS MCP server for verified WeChat reading, sending, media, and token-efficient allowlisted monitoring. Its Docker image supports registry introspection only; real WeChat automation requires macOS Accessibility.610MIT
- AlicenseNot gradedqualityDmaintenanceA production-oriented MCP server that exposes task-level WeChat Desktop automation to AI clients, enabling status checks, message fetching/reply, contact addition, and Moment publishing on macOS via accessibility automation.3MIT
- AlicenseAqualityBmaintenanceEnables compatible AI assistants to operate Linux WeChat through local stdio, including contact and group search, bounded message history retrieval, private and group text sending, shared service lifecycle management, capability discovery, and persistent idempotent deduplication.220 npm1MIT