wecom-crm-mcp

WeCom (企业微信) 客户联系 / External Contact MCP Server — a Python SDK + Model Context Protocol server that covers the full customer-contact API surface so an LLM can manage customers, tags, group chats, moments, and mass-send messages on your behalf.

Why this exists

GitHub has plenty of WeCom group-bot webhook MCP servers. None covered the real 私域运营 / CRM surface exposed by 企业微信's 「客户联系」 API: customers, tags, group chats, 朋友圈, 群发, transfer-on-handover, acquisition links. This does — 11 modules, 63 actions, 1:1 with the official docs.

Coverage

#	Module	MCP tool	Key actions
1	客户管理	wecom_customer	list_followers, list, get, batch_get, remark
2	客户标签	wecom_tag	list_corp_tags, add_corp_tag, edit_corp_tag, del_corp_tag, mark_tag
3	在职继承	wecom_transfer_active	transfer_customer, transfer_result, group_chat_transfer
4	离职继承	wecom_transfer_resigned	get_unassigned_list, resigned_transfer_customer, resigned_transfer_result, groupchat_transfer
5	客户群	wecom_group_chat	list, get, opengid_to_chatid
6	联系我 / 加入群聊	wecom_contact_way	add, get, list, update, del, close_temp_chat, groupchat_*_join_way
7	客户朋友圈	wecom_moment	add_moment_task, get_moment_task_result, cancel_moment_task, get_moment_list, get_moment_task, get_moment_customer_list
8	获客助手	wecom_acquisition	create_link, list_links, get_link, update_link, delete_link, list_customers, get_quota, get_statistic
9	消息推送 / 群发	wecom_msg_template	add_msg_template, send_welcome_msg, get_groupmsg_list_v2, get_groupmsg_task, get_groupmsg_send_result
10	统计管理	wecom_statistics	get_user_behavior_data, groupchat_statistic, groupchat_statistic_group_by_day
11	附加功能	wecom_misc	product_album_*, *_intercept_rule, get_new_external_userid

Plus two helpers: wecom_upload_media (temporary media for attachments) and wecom_describe_action (list the actions each tool supports, so the LLM can self-introspect).

Install

pip install wecom-crm-mcp

Setup — 企业微信 Side

This is the part that trips most people up. Do it before you put credentials into the MCP config; otherwise you'll get errcode=60020 "not allow to access from your ip" on every call.

1. Find your 客户联系 secret

1. Log into work.weixin.qq.com as an admin
2. 客户联系 → 客户 → page bottom: API section
3. Click 配置 next to "API 接口" → you'll see Secret. Click 查看 and copy it. This is your WECOM_CORPSECRET.
4. In the same page, find your 企业ID (CorpID) from 我的企业 → bottom of the page. This is your WECOM_CORPID.

2. Add your server IP to the 可信 IP list

WeCom enforces IP whitelisting on the 客户联系 API. Every IP that calls the API must be whitelisted, including your laptop if you run the MCP locally.

The whitelist lives in the same 客户联系 → API page where you got the secret (not in the generic "应用管理 → 企业可信IP" — that one asks for a filed domain and is for self-built apps, not 客户联系).

Find your current public IP with:

curl https://ipinfo.io/ip

Paste it in, separated by ; if multiple.

Running from a laptop on home Wi‑Fi / VPN means your IP will change. Either (a) pin a stable exit via a cloud VM and run the MCP there, or (b) re-add the IP every time it changes. See deploy/README.md for the cloud-VM pattern.

3. Give the secret access to the employees whose customers it should manage

Still on 客户联系 → API → 可调用接口的应用 → add the employees/departments whose customer list you want the API to see. The secret can only read customers serviced by these people.

Setup — Client Side

Claude Desktop / Claude Code

Add to ~/.claude.json (or ~/Library/Application Support/Claude/claude_desktop_config.json for Claude Desktop):

{
  "mcpServers": {
    "wecom-crm": {
      "command": "wecom-crm-mcp",
      "env": {
        "WECOM_CORPID": "ww...",
        "WECOM_CORPSECRET": "...",
        "WECOM_AGENTID": "1000001"
      }
    }
  }
}

WECOM_AGENTID is only required for mass-send (wecom_msg_template); everything else works without it.

Restart the client and you should see a wecom-crm server with 13 tools.

Plain Python

import asyncio
from wecom_crm_mcp import WecomClient, WecomConfig
from wecom_crm_mcp.modules.customer import CustomerModule

async def main():
    cfg = WecomConfig.from_env()  # reads WECOM_CORPID / WECOM_CORPSECRET
    async with WecomClient(cfg) as c:
        customers = await CustomerModule(c).list_followers()
        print(customers)

asyncio.run(main())

Example LLM sessions

User: 列出所有带"VIP"标签的客户
Claude → wecom_tag (list_corp_tags)
       → wecom_customer (batch_get)
       → returns list

User: 帮我给所有客户发朋友圈，文案"春节快乐"，附张 /tmp/banner.jpg
Claude → wecom_upload_media (attachment_type=2)
       → wecom_moment (add_moment_task, with media_id from above)
       → returns jobid

User: 我们销售小王离职了，把他的所有客户转给小李
Claude → wecom_transfer_resigned (get_unassigned_list)
       → wecom_transfer_resigned (resigned_transfer_customer)

Error codes you'll actually hit

errcode	Meaning	Fix
60011	no permission on this customer	The customer isn't served by any user listed in 可调用接口的应用
60020	IP not allowed	Add your current IP to the 可信 IP list
42001 / 40014	token expired / invalid	Handled automatically — the client refreshes and retries once
40003	invalid external_userid	You passed an app-scoped openid, not an external_userid — convert with wecom_misc action=get_new_external_userid

Architecture

┌──────────────────┐           stdio            ┌──────────────────────┐
│  Claude / LLM    │ ─────── MCP ─────────────▶ │  wecom-crm-mcp       │
└──────────────────┘                             │  (FastMCP server)    │
                                                 │                      │
                                                 │  ┌────────────────┐  │
                                                 │  │ 11 Tool routers│──┼─▶ action → SDK method
                                                 │  └────────────────┘  │
                                                 │  ┌────────────────┐  │
                                                 │  │  WecomClient   │──┼─▶ httpx.AsyncClient
                                                 │  │  • token cache │  │  + diskcache
                                                 │  │  • retry 42001 │  │
                                                 │  └────────────────┘  │
                                                 └──────────┬───────────┘
                                                            │ HTTPS
                                                            ▼
                                              qyapi.weixin.qq.com

Development

git clone https://github.com/andyleimc-source/wecom-crm-mcp.git
cd wecom-crm-mcp
uv venv && source .venv/bin/activate
uv pip install -e ".[dev]"
uv run pytest -q

All tests mock HTTP with pytest-httpx — no network, no credentials needed.

Contributing

Issues and PRs welcome. If you add an endpoint, the pattern is:

1. Add the method to the relevant src/wecom_crm_mcp/modules/*.py
2. Add one test in tests/modules/test_*.py asserting the JSON body or query params
3. If it's a new user-facing action, add it to the action table in src/wecom_crm_mcp/server.py

License

MIT — see LICENSE.

Disclaimer

This is an independent community project. Not affiliated with Tencent or 企业微信. Use at your own risk and stay within the 企业微信 API rate limits and policies.