@qwang007/wecom-mcp

WeCom (企业微信) MCP server. Exposes 79 WeCom tools, 8 MCP resources, and 3 MCP prompts for use with Claude Desktop, Claude Code, or any other MCP client.

| Module | Tools | Highlights | |---|---|---| | Contact | 3 | List departments, list/get users (privacy-stripped) | | Approval | 7 | Templates (CRUD + local cache eviction), apply/get/list approval instances. Auto-caches templates in MCP Resources for cross-session discovery | | Drive | 22 | Spaces + files + ACL + permissions; watermark / share-link controls. Local space cache for discoverability | | Doc | 47 | Documents, smartsheet (sheets/views/fields/records/field_groups/content_priv), forms, permissions, image upload. Local caches for docs + forms |

Plus 8 MCP Resources — all top-level resources a user creates are auto-cached and enumerable across sessions (WeCom has no corresponding list-API for any of them):

• wecom-approval://templates / wecom-approval://templates/{id}
• wecom-drive://spaces / …/spaces/{id} / …/spaces/{id}/files/{fatherid} / …/files/{fileid}
• wecom-doc://forms / wecom-doc://documents

Plus 3 MCP Prompts for the Drive module — guided workflows your client can invoke directly:

• organize-space — generate a file-organization plan for a space
• share-file — step-by-step share flow (info → permission → ACL → share URL)
• audit-permissions — space-wide permission audit report

Install

The server is distributed via npm and runs in any MCP client. Add it to your client config — no git clone needed.

Claude Desktop / Claude Code

Edit claude_desktop_config.json (Mac: ~/Library/Application Support/Claude/claude_desktop_config.json):

{
  "mcpServers": {
    "wecom": {
      "command": "npx",
      "args": ["-y", "@qwang007/wecom-mcp"],
      "env": {
        "WECOM_CORP_ID": "ww1234567890abcdef",
        "WECOM_CORP_SECRET": "your-self-built-app-secret",
        "WECOM_ADMIN_USERID": "your_admin_userid"
      }
    }
  }
}

Or with Bun:

{
  "mcpServers": {
    "wecom": {
      "command": "bunx",
      "args": ["-y", "@qwang007/wecom-mcp"],
      "env": { /* same as above */ }
    }
  }
}

Restart your MCP client. The 79 tools + 8 resources + 3 prompts will be available immediately.

Required environment variables

| Variable | Required | How to get | |---|---|---| | WECOM_CORP_ID | yes | 企微管理后台 → 我的企业 → 企业信息 → 企业 ID (18 chars, starts with ww) | | WECOM_CORP_SECRET | yes | 应用管理 → 你的自建应用 → Secret | | WECOM_ADMIN_USERID | needed for Drive + most Doc tools | 通讯录 → 你的账号 → userid（不是姓名） |

The corp must add your machine's outbound IP to the app's 企业可信IP list, or all API calls fail with 60020: not allow to access from your ip.

App permissions

Your self-built app needs these scopes enabled:

• 通讯录 → 查看
• 应用管理 → 微盘管理 (for Drive module)
• 办公 → 审批 接口读写 (for Approval module)
• 办公 → 文档 应用管理文档 (for Doc module)

Resource registry (MCP Resources)

WeCom has no list-API for several top-level resource types — once you create a template, space, document or form, the ID is returned once and there's no way to re-discover it later. This server bridges that gap with local per-corp JSON caches under ~/.wecom-mcp/<corp_id>/ (atomic rename, writeChain-serialized, path-traversal guarded):

| File | Resource URI | Populated by | |---|---|---| | approval-templates.json | wecom-approval://templates | approval_create_template / _update_template / _get_template | | drive-spaces.json | wecom-drive://spaces | drive_create_space / _rename_space / _get_space_info; auto-evicted by drive_dismiss_space | | doc-documents.json | wecom-doc://documents | doc_create / doc_rename(docid) / doc_get_info; auto-evicted by doc_delete(docid) | | doc-forms.json | wecom-doc://forms | doc_create_form / doc_modify_form(oper=1) / doc_get_form_info; auto-evicted by doc_delete(formid) |

Eviction: when WeCom itself has a delete API (drive spaces, docs), dismiss/delete tools auto-evict on success. When it doesn't (approval templates, forms deleted via admin UI), four *_evict_*_cache tools let the LLM sync the cache manually:

• approval_evict_template_cache(template_id)
• drive_evict_space_cache(spaceid)
• doc_evict_document_cache(docid)
• doc_evict_form_cache(formid)

All marked destructiveHint: true, all LOCAL-ONLY (never touch WeCom).

Local development

git clone <this-repo>
cd wecom-mcp
bun install
# create .env with the three required vars (see "Required environment variables" above)
bun run start             # stdio MCP server
bun test                  # all unit tests
bun run test:integration  # smoke tests (no live API)
bun run typecheck

Live API smoke (requires .env + IP whitelist):

• bun run scripts/check-token.ts — verify connectivity
• bun run scripts/live-smoke.ts — Contact module read-only sweep
• bun run scripts/cache-template.ts <template_id> — seed approval cache from existing WeCom template
• bun run scripts/uncache-template.ts <template_id> — remove from cache

License

MIT — see LICENSE.