Wechat Official Account MCP

🚀 WeChat Official Account MCP Service

This is an MCP (Model Context Protocol) service project that integrates the WeChat Official Account API for AI applications.

Author: xwang152-jack xwang152@163.com
Last Updated: November 20, 2025

🚀 Quick Start

Option 1: Use npx (Recommended)

Run directly with npx without installation:

# Start the MCP server
npx wechat-official-account-mcp mcp -a <your_app_id> -s <your_app_secret>

# Example
npx wechat-official-account-mcp mcp -a wx1234567890abcdef -s your_app_secret_here

💡 Usage Tip

If you use the SSE mode, set CORS_ORIGIN to the whitelist of allowed domain names.

Option 2: Global Installation

# Install globally
npm install -g wechat-official-account-mcp

# Start the service
wechat-mcp mcp -a <your_app_id> -s <your_app_secret>

Option 3: Local Development

# 1. Clone the project
git clone https://github.com/xwang152-jack/wechat-official-account-mcp.git
cd wechat-official-account-mcp

# 2. Install dependencies
npm install

# 3. Build the project
npm run build

# 4. Start the service
node dist/src/cli.js mcp -a <your_app_id> -s <your_app_secret>

CLI Parameter Explanation

• -a, --app-id <appId>: WeChat Official Account AppID (Required)
• -s, --app-secret <appSecret>: WeChat Official Account AppSecret (Required)
• -m, --mode <mode>: Transmission mode, supports stdio (default) and sse
• -p, --port <port>: Port number in SSE mode (default 3000)
• -h, --help: Display help information

Commonly used environment variables:

• CORS_ORIGIN: Comma-separated whitelist of cross - origin sources (Example: https://a.example.com,https://b.example.com)
• WECHAT_MCP_SECRET_KEY: Enable encrypted storage of sensitive fields (AES), enabled when set

✨ Features

• 🔐 Authentication Management: Securely manage WeChat Official Account AppID, AppSecret, and Access Token.
• 📁 Media Management: Upload, retrieve, and manage temporary and permanent media.
• 📝 Draft Management: Create, edit, and manage graphic drafts.
• 📢 Publication Management: Publish drafts to the WeChat Official Account.
• 💾 Local Storage: Use SQLite for local storage of configurations and data.
• 🔧 MCP Integration: Fully compatible with the MCP protocol standard.
• 🛡️ Security Enhancement (v1.1.0): Support encrypted storage of sensitive fields and log desensitization, and configure cross - origin source whitelists.

🛠️ Technology Stack

📦 Installation

Option 1: Use npx (Recommended)

# Start the MCP server
npx wechat-official-account-mcp mcp -a <your_app_id> -s <your_app_secret>

# Example
npx wechat-official-account-mcp mcp -a wx1234567890abcdef -s your_app_secret_here

Option 2: Global Installation

# Install globally
npm install -g wechat-official-account-mcp

# Start the service
wechat-mcp mcp -a <your_app_id> -s <your_app_secret>

Option 3: Local Development

# 1. Clone the project
git clone https://github.com/xwang152-jack/wechat-official-account-mcp.git
cd wechat-official-account-mcp

# 2. Install dependencies
npm install

# 3. Build the project
npm run build

# 4. Start the service
node dist/src/cli.js mcp -a <your_app_id> -s <your_app_secret>

🔧 MCP Tool List

1. Authentication Tool (wechat_auth)

Manage WeChat Official Account authentication configurations and Access Token.

Supported Operations:

• configure: Configure AppID and AppSecret.
• get_token: Get the current Access Token.
• refresh_token: Refresh the Access Token.
• get_config: View the current configuration.

2. Media Upload Tool (wechat_media_upload)

Upload and manage temporary media for the WeChat Official Account.

Supported Operations:

• upload: Upload media (images, voices, videos, thumbnails).
• get: Get media information.
• list: Not supported yet (Temporary media is valid for 3 days. It is recommended to use the permanent media function).

Supported Formats:

• Images: JPG, PNG (Size not exceeding 10MB).
• Voices: MP3, WMA, WAV, AMR (Size not exceeding 10MB, duration not exceeding 60s).
• Videos: MP4 (Size not exceeding 10MB).
• Thumbnails: JPG (Size not exceeding 64KB).

3. Image Upload Tool for Graphic Messages (wechat_upload_img)

Upload images required in graphic messages without occupying the media library limit.

Supported Operations:

• upload: Upload images (supports file paths or base64 data).

Supported Formats:

• Images: JPG, PNG (Size not exceeding 1MB).

Features:

• Does not occupy the 100,000 - image limit of the official account's media library.
• Specifically for images in graphic message content.
• Returns an image URL that can be directly used in graphic messages.

4. Permanent Media Tool (wechat_permanent_media)

Manage permanent media for the WeChat Official Account.

Supported Operations:

• add: Upload permanent media (images, voices, videos, thumbnails).
• get: Get permanent media.
• delete: Delete permanent media.
• list: Get the media list.
• count: Get the total number of media.

5. Draft Management Tool (wechat_draft)

Manage graphic drafts for the WeChat Official Account.

Supported Operations:

• add: Create a new draft.
• get: Get draft details.
• delete: Delete a draft.
• list: Get the draft list.
• count: Get the total number of drafts.

6. Publication Tool (wechat_publish)

Manage article publication for the WeChat Official Account.

Supported Operations:

• submit: Publish a draft.
• get: Get the publication status.
• delete: Delete a publication.
• list: Get the publication list.

📁 Project Structure

src/
├── cli.ts               # CLI entry file
├── index.ts             # Module export entry
├── mcp-server/          # MCP server implementation
│   ├── shared/          # Shared components
│   │   ├── init.ts      # Server initialization
│   │   └── types.ts     # Type definitions
│   └── transport/       # Transport layer implementation
│       ├── stdio.ts     # stdio transport
│       └── sse.ts       # SSE transport
├── mcp-tool/            # MCP tool implementation
│   ├── index.ts         # Tool manager
│   ├── types.ts         # Type definitions
│   └── tools/           # Specific tool implementation
│       ├── index.ts
│       ├── auth-tool.ts
│       ├── media-upload-tool.ts
│       ├── upload-img-tool.ts
│       ├── permanent-media-tool.ts
│       ├── draft-tool.ts
│       └── publish-tool.ts
├── auth/                # Authentication management
│   └── auth-manager.ts
├── wechat/              # WeChat API client
│   └── api-client.ts
├── storage/             # Data storage
│   └── storage-manager.ts
└── utils/               # Utility functions
    ├── logger.ts
    └── db-init.ts

💻 Usage Examples

In Claude Desktop

Add the following to claude_desktop_config.json:

{
  "mcpServers": {
    "wechat-official-account": {
      "command": "npx",
      "args": [
        "wechat-official-account-mcp",
        "mcp",
        "-a", "your_wechat_app_id",
        "-s", "your_wechat_app_secret"
      ]
    }
  }
}

Or use the globally installed version:

{
  "mcpServers": {
    "wechat-official-account": {
      "command": "wechat-mcp",
      "args": [
        "mcp",
        "-a", "your_wechat_app_id",
        "-s", "your_wechat_app_secret"
      ]
    }
  }
}

In Cursor / Trae AI

Add the server configuration to the MCP configuration:

{
  "mcpServers": {
    "wechat-official-account": {
      "command": "npx",
      "args": [
        "wechat-official-account-mcp",
        "mcp",
        "-a", "your_wechat_app_id",
        "-s", "your_wechat_app_secret"
      ]
    }
  }
}

Or use the globally installed version:

{
  "mcpServers": {
    "wechat-official-account": {
      "command": "wechat-mcp",
      "args": [
        "mcp",
        "-a", "your_wechat_app_id",
        "-s", "your_wechat_app_secret"
      ]
    }
  }
}

📚 Documentation

Development Mode

# Install dependencies
npm install

# Build the project
npm run build

# Test the CLI locally
node dist/src/cli.js mcp -a test_app_id -s test_app_secret

# Type checking
npm run check

# Code checking
npm run lint

Build and Publish

# Build the project
npm run build

# Test the package locally
npm pack

# Publish to npm
npm publish

Testing

# Run tests
npm test

# Test CLI functionality
node dist/src/cli.js --help

Configuration Explanation

Environment Variables

Create a .env file:

# Development mode (Optional)
NODE_ENV=development

# Debug mode (Optional)
DEBUG=true

# Cross - origin source whitelist (Highly recommended for production environment)
CORS_ORIGIN=https://your-domain.com,https://another-domain.com

# Enable encryption of sensitive fields (Enables AES encrypted storage after setting)
WECHAT_MCP_SECRET_KEY=your-strong-secret-key

# Database path (Optional, default is ./data/wechat-mcp.db)
DB_PATH=./data/wechat-mcp.db

WeChat Official Account Configuration

1. Log in to the WeChat Public Platform.
2. Go to 「Development」 -> 「Basic Configuration」.
3. Obtain the AppID and AppSecret.
4. Configure using the wechat_auth tool.

🔒 Security Explanation

⚠️ Important Note

• Encrypted Storage: After setting WECHAT_MCP_SECRET_KEY, app_secret/token/encoding_aes_key/access_token are persistently stored in an encrypted form (identified with the enc: prefix).
• Log Desensitization: Error logs only record status codes or messages to avoid leaking response bodies and sensitive information.
• Cross - Origin Whitelist: In the production environment, be sure to set CORS_ORIGIN to an accurate list of domain names, avoiding *.
• Parameter Validation: Tool parameters are validated using Zod to reduce the risk of improper input.
• Do not submit keys: Do not put AppSecret, Token, etc. into the code repository or build artifacts.

🤝 Contribution Guidelines

1. Fork this project.
2. Create a feature branch (git checkout -b feature/AmazingFeature).
3. Commit changes (git commit -m 'Add some AmazingFeature').
4. Push to the branch (git push origin feature/AmazingFeature).
5. Open a Pull Request.

📄 License

This project is licensed under the MIT License. See the LICENSE file for details.

🆘 Support

If you encounter problems or have suggestions, please:

1. Check the Issues page.
2. Create a new Issue.
3. Contact the project maintainer: xwang152-jack xwang152@163.com

🙏 Acknowledgments

• Model Context Protocol - MCP protocol standard
• WeChat Public Platform - WeChat Official Account API
• Anthropic - Claude Desktop MCP support

⚠️ Important Note

This project is for learning and development purposes only. Please comply with the usage terms of the WeChat Public Platform and relevant laws and regulations.