Servidor MCP de WeCom Bot

Una implementación de servidor compatible con el Protocolo de Contexto Modelo (MCP) para el bot WeCom (WeChat Work).

Versión de PyPI Versión de Python código decodificador Estilo de código: ruff insignia de herrería

inglés |中文

Características

Compatibilidad con múltiples tipos de mensajes:
- mensajes de texto
- Mensajes de Markdown
- Mensajes de imagen (base64)
- Mensajes de archivo
Soporte de @mention (a través de ID de usuario o número de teléfono)
Seguimiento del historial de mensajes
Sistema de registro configurable
Anotaciones de tipo completo
Validación de datos basada en Pydantic

Related MCP server: MCP Webhook Server

Requisitos

Python 3.10+
URL del webhook del bot WeCom (obtenida de la configuración del grupo WeCom)

Instalación

Hay varias formas de instalar WeCom Bot MCP Server:

1. Instalación automatizada (recomendada)

Uso de Smithery (para Claude Desktop):

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

Uso de VSCode con la extensión Cline:

Instalar la extensión Cline desde el marketplace de VSCode
Abrir la paleta de comandos (Ctrl+Mayús+P / Cmd+Mayús+P)
Buscar "Cline: Instalar paquete"
Escriba "wecom-bot-mcp-server" y presione Enter

2. Instalación manual

Instalar desde PyPI:

pip install wecom-bot-mcp-server

Configurar MCP manualmente:

Cree o actualice su archivo de configuración MCP:

// For Windsurf: ~/.windsurf/config.json
{
  "mcpServers": {
    "wecom": {
      "command": "uvx",
      "args": [
        "wecom-bot-mcp-server"
      ],
      "env": {
        "WECOM_WEBHOOK_URL": "your-webhook-url"
      }
    }
  }
}

Configuración

Configuración de variables de entorno

# Windows PowerShell
$env:WECOM_WEBHOOK_URL = "your-webhook-url"

# Optional configurations
$env:MCP_LOG_LEVEL = "DEBUG"  # Log levels: DEBUG, INFO, WARNING, ERROR, CRITICAL
$env:MCP_LOG_FILE = "path/to/custom/log/file.log"  # Custom log file path

Gestión de registros

El sistema de registro utiliza platformdirs.user_log_dir() para la gestión de archivos de registro multiplataforma:

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

El archivo de registro se llama mcp_wecom.log y se almacena en el directorio mencionado anteriormente.

Uso

Iniciando el servidor

wecom-bot-mcp-server

Ejemplos de uso (con MCP)

# Scenario 1: Send weather information to WeCom
USER: "How's the weather in Shenzhen today? Send it to WeCom"
ASSISTANT: "I'll check Shenzhen's weather and send it to WeCom"

await mcp.send_message(
    content="Shenzhen Weather:\n- Temperature: 25°C\n- Weather: Sunny\n- Air Quality: Good",
    msg_type="markdown"
)

# Scenario 2: Send meeting reminder and @mention relevant people
USER: "Send a reminder for the 3 PM project review meeting, remind Zhang San and Li Si to attend"
ASSISTANT: "I'll send the meeting reminder"

await mcp.send_message(
    content="## Project Review Meeting Reminder\n\nTime: Today 3:00 PM\nLocation: Meeting Room A\n\nPlease be on time!",
    msg_type="markdown",
    mentioned_list=["zhangsan", "lisi"]
)

# Scenario 3: Send a file
USER: "Send this weekly report to the WeCom group"
ASSISTANT: "I'll send the weekly report"

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

Uso directo de la API

Enviar mensajes

from wecom_bot_mcp_server import mcp

# Send markdown message
await mcp.send_message(
    content="**Hello World!**", 
    msg_type="markdown"
)

# Send text message and mention users
await mcp.send_message(
    content="Hello @user1 @user2",
    msg_type="text",
    mentioned_list=["user1", "user2"]
)

Enviar archivos

from wecom_bot_mcp_server import send_wecom_file

# Send file
await send_wecom_file("/path/to/file.txt")

Enviar imágenes

from wecom_bot_mcp_server import send_wecom_image

# Send local image
await send_wecom_image("/path/to/image.png")

# Send URL image
await send_wecom_image("https://example.com/image.png")

Desarrollo

Configurar el entorno de desarrollo

Clonar el repositorio:

git clone https://github.com/loonghao/wecom-bot-mcp-server.git
cd wecom-bot-mcp-server

Cree un entorno virtual e instale dependencias:

# Using uv (recommended)
pip install uv
uv venv
uv pip install -e ".[dev]"

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

Pruebas

# Using uv (recommended)
uvx nox -s pytest

# Or using traditional method
nox -s pytest

Estilo de código

# Check code
uvx nox -s lint

# Automatically fix code style issues
uvx nox -s lint_fix

Construcción y publicación

# Build the package
uv build

# Build and publish to PyPI
uv build && twine upload dist/*

Estructura del proyecto

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

Licencia

Este proyecto está licenciado bajo la licencia MIT: consulte el archivo de LICENCIA para obtener más detalles.

Contacto

Autor: longhao
Correo electrónico: hal.long@outlook.com

WeCom Bot MCP Server