{"id":50527663,"url":"https://github.com/andyleimc-source/wecom-crm-mcp","last_synced_at":"2026-06-03T09:30:24.668Z","repository":{"id":359048608,"uuid":"1212189126","full_name":"andyleimc-source/wecom-crm-mcp","owner":"andyleimc-source","description":"WeCom (企业微信) External Contact (客户联系) MCP server — Python SDK + MCP covering customers, tags, moments, mass-send, group chats, transfers, statistics (11 modules, 60+ APIs).","archived":false,"fork":false,"pushed_at":"2026-04-16T07:13:22.000Z","size":27,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-05-20T09:48:19.103Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":null,"language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/andyleimc-source.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2026-04-16T06:29:55.000Z","updated_at":"2026-04-16T07:13:26.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/andyleimc-source/wecom-crm-mcp","commit_stats":null,"previous_names":["andyleimc-source/wecom-crm-mcp"],"tags_count":1,"template":false,"template_full_name":null,"purl":"pkg:github/andyleimc-source/wecom-crm-mcp","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/andyleimc-source%2Fwecom-crm-mcp","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/andyleimc-source%2Fwecom-crm-mcp/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/andyleimc-source%2Fwecom-crm-mcp/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/andyleimc-source%2Fwecom-crm-mcp/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/andyleimc-source","download_url":"https://codeload.github.com/andyleimc-source/wecom-crm-mcp/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/andyleimc-source%2Fwecom-crm-mcp/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":33858569,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-05-26T15:22:16.424Z","status":"online","status_checked_at":"2026-06-03T02:00:06.370Z","response_time":59,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2026-06-03T09:30:23.245Z","updated_at":"2026-06-03T09:30:24.651Z","avatar_url":"https://github.com/andyleimc-source.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"# wecom-crm-mcp\n\n\u003e 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.\n\n[![PyPI](https://img.shields.io/pypi/v/wecom-crm-mcp.svg)](https://pypi.org/project/wecom-crm-mcp/)\n[![Python](https://img.shields.io/pypi/pyversions/wecom-crm-mcp.svg)](https://pypi.org/project/wecom-crm-mcp/)\n[![License](https://img.shields.io/badge/license-MIT-blue.svg)](LICENSE)\n\n## Why this exists\n\nGitHub 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](https://developer.work.weixin.qq.com/document/path/90664).\n\n## Coverage\n\n| # | Module | MCP tool | Key actions |\n|---|---|---|---|\n| 1 | 客户管理 | `wecom_customer` | `list_followers`, `list`, `get`, `batch_get`, `remark` |\n| 2 | 客户标签 | `wecom_tag` | `list_corp_tags`, `add_corp_tag`, `edit_corp_tag`, `del_corp_tag`, `mark_tag` |\n| 3 | 在职继承 | `wecom_transfer_active` | `transfer_customer`, `transfer_result`, `group_chat_transfer` |\n| 4 | 离职继承 | `wecom_transfer_resigned` | `get_unassigned_list`, `resigned_transfer_customer`, `resigned_transfer_result`, `groupchat_transfer` |\n| 5 | 客户群 | `wecom_group_chat` | `list`, `get`, `opengid_to_chatid` |\n| 6 | 联系我 / 加入群聊 | `wecom_contact_way` | `add`, `get`, `list`, `update`, `del`, `close_temp_chat`, `groupchat_*_join_way` |\n| 7 | 客户朋友圈 | `wecom_moment` | `add_moment_task`, `get_moment_task_result`, `cancel_moment_task`, `get_moment_list`, `get_moment_task`, `get_moment_customer_list` |\n| 8 | 获客助手 | `wecom_acquisition` | `create_link`, `list_links`, `get_link`, `update_link`, `delete_link`, `list_customers`, `get_quota`, `get_statistic` |\n| 9 | 消息推送 / 群发 | `wecom_msg_template` | `add_msg_template`, `send_welcome_msg`, `get_groupmsg_list_v2`, `get_groupmsg_task`, `get_groupmsg_send_result` |\n| 10 | 统计管理 | `wecom_statistics` | `get_user_behavior_data`, `groupchat_statistic`, `groupchat_statistic_group_by_day` |\n| 11 | 附加功能 | `wecom_misc` | `product_album_*`, `*_intercept_rule`, `get_new_external_userid` |\n\nPlus 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).\n\n## Install\n\n```bash\npip install wecom-crm-mcp\n```\n\n## Setup — 企业微信 Side\n\n\u003e 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.\n\n### 1. Find your 客户联系 secret\n\n1. Log into [work.weixin.qq.com](https://work.weixin.qq.com/) as an admin\n2. **客户联系** → **客户** → page bottom: **API** section\n3. Click **配置** next to \"API 接口\" → you'll see **Secret**. Click **查看** and copy it. This is your `WECOM_CORPSECRET`.\n4. In the same page, find your **企业ID (CorpID)** from **我的企业** → bottom of the page. This is your `WECOM_CORPID`.\n\n### 2. Add your server IP to the 可信 IP list\n\nWeCom enforces IP whitelisting on the 客户联系 API. **Every IP that calls the API must be whitelisted**, including your laptop if you run the MCP locally.\n\nThe 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 客户联系).\n\nFind your current public IP with:\n\n```bash\ncurl https://ipinfo.io/ip\n```\n\nPaste it in, separated by `;` if multiple.\n\n\u003e 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](deploy/README.md) for the cloud-VM pattern.\n\n### 3. Give the secret access to the employees whose customers it should manage\n\nStill 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.\n\n## Setup — Client Side\n\n### Claude Desktop / Claude Code\n\nAdd to `~/.claude.json` (or `~/Library/Application Support/Claude/claude_desktop_config.json` for Claude Desktop):\n\n```json\n{\n  \"mcpServers\": {\n    \"wecom-crm\": {\n      \"command\": \"wecom-crm-mcp\",\n      \"env\": {\n        \"WECOM_CORPID\": \"ww...\",\n        \"WECOM_CORPSECRET\": \"...\",\n        \"WECOM_AGENTID\": \"1000001\"\n      }\n    }\n  }\n}\n```\n\n`WECOM_AGENTID` is only required for mass-send (`wecom_msg_template`); everything else works without it.\n\nRestart the client and you should see a `wecom-crm` server with 13 tools.\n\n### Plain Python\n\n```python\nimport asyncio\nfrom wecom_crm_mcp import WecomClient, WecomConfig\nfrom wecom_crm_mcp.modules.customer import CustomerModule\n\nasync def main():\n    cfg = WecomConfig.from_env()  # reads WECOM_CORPID / WECOM_CORPSECRET\n    async with WecomClient(cfg) as c:\n        customers = await CustomerModule(c).list_followers()\n        print(customers)\n\nasyncio.run(main())\n```\n\n## Example LLM sessions\n\n```\nUser: 列出所有带\"VIP\"标签的客户\nClaude → wecom_tag (list_corp_tags)\n       → wecom_customer (batch_get)\n       → returns list\n```\n\n```\nUser: 帮我给所有客户发朋友圈，文案\"春节快乐\"，附张 /tmp/banner.jpg\nClaude → wecom_upload_media (attachment_type=2)\n       → wecom_moment (add_moment_task, with media_id from above)\n       → returns jobid\n```\n\n```\nUser: 我们销售小王离职了，把他的所有客户转给小李\nClaude → wecom_transfer_resigned (get_unassigned_list)\n       → wecom_transfer_resigned (resigned_transfer_customer)\n```\n\n## Error codes you'll actually hit\n\n| errcode | Meaning | Fix |\n|---|---|---|\n| `60011` | no permission on this customer | The customer isn't served by any user listed in 可调用接口的应用 |\n| `60020` | IP not allowed | Add your current IP to the 可信 IP list |\n| `42001` / `40014` | token expired / invalid | Handled automatically — the client refreshes and retries once |\n| `40003` | invalid external_userid | You passed an app-scoped openid, not an external_userid — convert with `wecom_misc action=get_new_external_userid` |\n\n## Architecture\n\n```\n┌──────────────────┐           stdio            ┌──────────────────────┐\n│  Claude / LLM    │ ─────── MCP ─────────────▶ │  wecom-crm-mcp       │\n└──────────────────┘                             │  (FastMCP server)    │\n                                                 │                      │\n                                                 │  ┌────────────────┐  │\n                                                 │  │ 11 Tool routers│──┼─▶ action → SDK method\n                                                 │  └────────────────┘  │\n                                                 │  ┌────────────────┐  │\n                                                 │  │  WecomClient   │──┼─▶ httpx.AsyncClient\n                                                 │  │  • token cache │  │  + diskcache\n                                                 │  │  • retry 42001 │  │\n                                                 │  └────────────────┘  │\n                                                 └──────────┬───────────┘\n                                                            │ HTTPS\n                                                            ▼\n                                              qyapi.weixin.qq.com\n```\n\n## Development\n\n```bash\ngit clone https://github.com/andyleimc-source/wecom-crm-mcp.git\ncd wecom-crm-mcp\nuv venv \u0026\u0026 source .venv/bin/activate\nuv pip install -e \".[dev]\"\nuv run pytest -q\n```\n\nAll tests mock HTTP with `pytest-httpx` — no network, no credentials needed.\n\n## Contributing\n\nIssues and PRs welcome. If you add an endpoint, the pattern is:\n\n1. Add the method to the relevant `src/wecom_crm_mcp/modules/*.py`\n2. Add one test in `tests/modules/test_*.py` asserting the JSON body or query params\n3. If it's a new user-facing action, add it to the action table in `src/wecom_crm_mcp/server.py`\n\n## License\n\nMIT — see [LICENSE](LICENSE).\n\n## Disclaimer\n\nThis is an independent community project. Not affiliated with Tencent or 企业微信. Use at your own risk and stay within the [企业微信 API rate limits and policies](https://developer.work.weixin.qq.com/document/path/90313).\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fandyleimc-source%2Fwecom-crm-mcp","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fandyleimc-source%2Fwecom-crm-mcp","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fandyleimc-source%2Fwecom-crm-mcp/lists"}