Enterprise Communication Bridge for WeCom

This repository offers an MCP-compliant backend service engineered to interface with WeCom (WeChat Work) bots through their secure webhook mechanism.

English Documentation | 中文指南

Core Capabilities

This utility provides robust support for various message formats:

• Textual payloads
• Markdown compositions
• Binary attachments (encoded via base64)
• Standard document transfers

Additionally, it supports:

• Targeted user notifications via user ID or mobile contact number linkage
• Auditing of transmitted message history
• Adaptable diagnostic output configuration
• Comprehensive static typing across the codebase
• Data schema verification utilizing Pydantic models

Prerequisites

• Requires Python interpreter version 3.10 or newer
• A valid Webhook Uniform Resource Locator (URL) obtained from the WeCom Group configuration panel

Acquisition Methods

There are multiple avenues for deploying the WeCom Bot MCP Server:

1. Automated Deployment (Recommended Path)

Via Smithery (For use with Claude Desktop):

bash npx -y @smithery/cli install wecom-bot-mcp-server --client claude

Via VSCode using the Cline Extension:

1. Install the Cline Extension from the VSCode marketplace.
2. Access the Command Palette (Ctrl+Shift+P / Cmd+Shift+P).
3. Search for and select "Cline: Install Package".
4. Input "wecom-bot-mcp-server" and finalize with Enter.

2. Manual Installation

Installation via PyPI registry:

bash pip install wecom-bot-mcp-server

MCP Configuration Setup:

Modify or establish your main MCP configuration file:

// Example for Windsurf configuration: ~/.windsurf/config.json { "mcpServers": { "wecom": { "command": "uvx", "args": [ "wecom-bot-mcp-server" ], "env": { "WECOM_WEBHOOK_URL": "your-provided-webhook-endpoint" } } } }

Configuration Parameters

Defining Environmental Variables

bash

For Windows PowerShell users

$env:WECOM_WEBHOOK_URL = "your-provided-webhook-endpoint"

Optional settings for diagnostics

$env:MCP_LOG_LEVEL = "DEBUG" # Permissible values: DEBUG, INFO, WARNING, ERROR, CRITICAL $env:MCP_LOG_FILE = "/custom/path/to/system/log/file.log" # Specify an alternative file location

Diagnostic Log Handling

The integrated logging subsystem employs platformdirs.user_log_dir() to ensure cross-platform log file placement:

• Windows OS: C:\Users\<username>\AppData\Local\hal\wecom-bot-mcp-server
• Linux OS: ~/.local/share/hal/wecom-bot-mcp-server
• macOS OS: ~/Library/Application Support/hal/wecom-bot-mcp-server

The standard log artifact is named mcp_wecom.log and resides within the directory specified above.

Operational Guidance

Launching the Service

Execute the primary command:

bash wecom-bot-mcp-server

Practical Application Examples (Leveraging MCP)

python

Use Case 1: Disseminating current meteorological data to WeCom channels

USER: "What is the current weather status in Shenzhen? Relay this data via WeCom" ASSISTANT: "I will query Shenzhen's conditions and transmit the findings to WeCom"

await mcp.send_message( content="Shenzhen Conditions:\n- Temperature: 25° Celsius\n- Status: Clear Skies\n- Air Quality Index: Acceptable", msg_type="markdown" )

Use Case 2: Issuing a session commencement notice with targeted user tagging

USER: "Notify participants about the 3 PM technical review, ensure Zhang San and Li Si are alerted" ASSISTANT: "Acknowledged, distributing the meeting advisory now"

await mcp.send_message( content="## Technical Review Session Advisory\n\nSchedule: Today at 15:00 hours\nVenue: Conference Room A\nAttendance is mandatory!", msg_type="markdown", mentioned_list=["zhangsan", "lisi"] )

Use Case 3: Transferring an associated document

USER: "Transmit this finalized weekly performance dossier to the designated WeCom forum" ASSISTANT: "Proceeding with the file transfer"

await mcp.send_message( content=Path("weekly_report.docx"), msg_type="file" )

Direct Interface Interactions

Transmitting Messages

python from wecom_bot_mcp_server import mcp

Sending a formatted markdown notification

await mcp.send_message( content="System Alert Initiated!", msg_type="markdown" )

Sending plain text and specifically tagging individuals

await mcp.send_message( content="Greetings @person_a and @person_b", msg_type="text", mentioned_list=["person_a", "person_b"] )

File Transmission Utility

python from wecom_bot_mcp_server import send_wecom_file

Upload and share a local data artifact

await send_wecom_file("/absolute/path/to/data.pdf")

Image Broadcast Utility

python from wecom_bot_mcp_server import send_wecom_image

Broadcasting an image stored locally

await send_wecom_image("/local/assets/chart.jpeg")

Broadcasting an image referenced by its network address

await send_wecom_image("https://external-source.com/visual.jpg")

Contribution & Development

Environment Setup for Modification

1. Obtain a local copy of the source code repository: bash git clone https://github.com/loonghao/wecom-bot-mcp-server.git cd wecom-bot-mcp-server

2. Establish an isolated execution context and install required libraries: bash

Using the 'uv' toolchain (preferred method)

pip install uv uv venv uv pip install -e ".[dev]"

Alternatively, using standard Python tooling

python -m venv venv source venv/bin/activate # On Windows: venv\Scripts\activate pip install -e ".[dev]"

Verification Procedures

bash

Execute test suites using uvx

uvx nox -s pytest

Or via traditional nox invocation

nox -s pytest

Code Formatting Standards

bash

Check adherence to style guides

uvx nox -s lint

Apply automatic style corrections

uvx nox -s lint_fix

Build and Distribution

bash

Compile the distributable package artifacts

uv build

Compile and upload to the official PyPI repository

uv build && twine upload dist/*

Repository Layout

wecom-bot-mcp-server/ ├── src/ │ └── wecom_bot_mcp_server/ │ ├── init.py │ ├── server.py │ ├── message.py │ ├── file.py │ ├── image.py │ ├── utils.py │ └── errors.py ├── tests/ │ ├── test_server.py │ ├── test_message.py │ ├── test_file.py │ └── test_image.py ├── docs/ ├── pyproject.toml ├── noxfile.py └── README.md

Licensing Information

This software is distributed under the terms specified in the MIT License (refer to the LICENSE file for comprehensive details).

Contact Point

• Developer: longhao
• Electronic Mail: hal.long@outlook.com

BUSINESS MANAGEMENT TOOLS OVERVIEW: Business management systems encompass all applications, controls, algorithmic solutions, operative methods, and specialized instruments utilized by organizations to maintain adaptability against market shifts, secure competitive standing, and enhance operational effectiveness. These utilities often span departmental boundaries, addressing functions such as strategic forecasting, process governance, data retention, personnel administration, decision support, and performance monitoring.

Evolution in management technology has been rapid in the last decade due to technological acceleration, making optimal tool selection challenging amid cost pressures, sales targets, and the imperative to deeply understand and fulfill customer demands. Managers must adopt a strategic, adaptive approach to incorporating new systems rather than passively adopting the newest releases, which often leads to organizational instability. Careful selection and subsequent tailoring of business management utilities to meet specific organizational requirements are paramount.

Historically significant tools, as evidenced by surveys, include Strategic Planning, CRM, Benchmarking, Balanced Scorecard implementation, and Supply Chain Optimization. The digital transformation has seen management information systems evolve into ERP, CRM solutions, and subsequently migrate to cloud-based management platforms. Value realization from IT investments hinges critically on effective deployment strategies and the judicious choice and customization of the underlying technologies.