Wechat Official Account MCP

🚀 微信公眾號 MCP 服務

本項目是一個基於 MCP 協議的服務項目，旨在為 AI 應用提供微信公眾號 API 的無縫集成。通過標準化的工具接口，AI 應用能夠輕鬆管理微信公眾號的素材、草稿、發佈等功能。

🚀 快速開始

本項目提供了三種啟動方式，你可以根據自己的需求進行選擇。

方式一：使用 npx（推薦）

直接使用 npx 運行，無需安裝：

# 啟動 MCP 服務器
npx wechat-official-account-mcp mcp -a <your_app_id> -s <your_app_secret>

# 示例
npx wechat-official-account-mcp mcp -a wx1234567890abcdef -s your_app_secret_here

⚠️ 重要提示

如使用 SSE 模式，請設置 CORS_ORIGIN 為允許訪問的域名白名單。

方式二：全局安裝

# 全局安裝
npm install -g wechat-official-account-mcp

# 啟動服務
wechat-mcp mcp -a <your_app_id> -s <your_app_secret>

方式三：本地開發

# 1. 克隆項目
git clone https://github.com/xwang152-jack/wechat-official-account-mcp.git
cd wechat-official-account-mcp

# 2. 安裝依賴
npm install

# 3. 構建項目
npm run build

# 4. 啟動服務
node dist/src/cli.js mcp -a <your_app_id> -s <your_app_secret>

CLI 參數說明

• -a, --app-id <appId>: 微信公眾號 AppID（必需）
• -s, --app-secret <appSecret>: 微信公眾號 AppSecret（必需）
• -m, --mode <mode>: 傳輸模式，支持 stdio（默認）和 sse
• -p, --port <port>: SSE 模式下的端口號（默認 3000）
• -h, --help: 顯示幫助信息

環境變量（常用）：

• CORS_ORIGIN: 逗號分隔的跨域來源白名單（示例：https://a.example.com,https://b.example.com）
• WECHAT_MCP_SECRET_KEY: 開啟敏感字段加密存儲（AES），設置即啟用

✨ 主要特性

• 🔐 認證管理：安全管理微信公眾號 AppID、AppSecret 和 Access Token。
• 📁 素材管理：上傳、獲取、管理臨時和永久素材。
• 📝 草稿管理：創建、編輯、管理圖文草稿。
• 📢 發佈管理：發佈草稿到微信公眾號。
• 💾 本地存儲：使用 SQLite 本地存儲配置和數據。
• 🔧 MCP 集成：完全兼容 MCP 協議標準。
• 🛡️ 安全增強（v1.1.0）：支持敏感字段加密存儲與日誌脫敏，跨域來源白名單配置。

📦 安裝指南

方式一：使用 npx（推薦）

npx wechat-official-account-mcp mcp -a <your_app_id> -s <your_app_secret>

方式二：全局安裝

npm install -g wechat-official-account-mcp

方式三：本地開發

git clone https://github.com/xwang152-jack/wechat-official-account-mcp.git
cd wechat-official-account-mcp
npm install
npm run build

💻 使用示例

在 AI 應用中使用

Claude Desktop

在 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"
      ]
    }
  }
}

或者使用全局安裝的版本：

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

Cursor / Trae AI

在 MCP 配置中添加服務器配置：

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

或者使用全局安裝的版本：

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

📚 詳細文檔

MCP 工具列表

1. 認證工具 (wechat_auth)

管理微信公眾號認證配置和 Access Token。 支持操作：

• configure：配置 AppID 和 AppSecret
• get_token：獲取當前 Access Token
• refresh_token：刷新 Access Token
• get_config：查看當前配置

2. 素材上傳工具 (wechat_media_upload)

上傳和管理微信公眾號臨時素材。 支持操作：

• upload：上傳素材（圖片、語音、視頻、縮略圖）
• get：獲取素材信息
• list：暫不支持（臨時素材有效期 3 天，建議使用永久素材功能）

支持格式：

• 圖片：JPG、PNG（大小不超過 10MB）
• 語音：MP3、WMA、WAV、AMR（大小不超過 10MB，時長不超過 60s）
• 視頻：MP4（大小不超過 10MB）
• 縮略圖：JPG（大小不超過 64KB）

3. 圖文消息圖片上傳工具 (wechat_upload_img)

上傳圖文消息內所需的圖片，不佔用素材庫限制。 支持操作：

• upload：上傳圖片（支持文件路徑或 base64 數據）

支持格式：

• 圖片：JPG、PNG（大小不超過 1MB）

特點：

• 不佔用公眾號素材庫的 100000 個圖片限制
• 專用於圖文消息內容中的圖片
• 返回可直接在圖文消息中使用的圖片 URL

4. 永久素材工具 (wechat_permanent_media)

管理微信公眾號永久素材。 支持操作：

• add：上傳永久素材（圖片、語音、視頻、縮略圖）
• get：獲取永久素材
• delete：刪除永久素材
• list：獲取素材列表
• count：獲取素材總數統計

5. 草稿管理工具 (wechat_draft)

管理微信公眾號圖文草稿。 支持操作：

• add：新建草稿
• get：獲取草稿詳情
• delete：刪除草稿
• list：獲取草稿列表
• count：獲取草稿總數

6. 發佈工具 (wechat_publish)

管理微信公眾號文章發佈。 支持操作：

• submit：發佈草稿
• get：獲取發佈狀態
• delete：刪除發佈
• list：獲取發佈列表

項目結構

src/
├── cli.ts               # CLI 入口文件
├── index.ts             # 模塊導出入口
├── mcp-server/          # MCP 服務器實現
│   ├── shared/          # 共享組件
│   │   ├── init.ts      # 服務器初始化
│   │   └── types.ts     # 類型定義
│   └── transport/       # 傳輸層實現
│       ├── stdio.ts     # stdio 傳輸
│       └── sse.ts       # SSE 傳輸
├── mcp-tool/            # MCP 工具實現
│   ├── index.ts         # 工具管理器
│   ├── types.ts         # 類型定義
│   └── tools/           # 具體工具實現
│       ├── index.ts
│       ├── auth-tool.ts
│       ├── media-upload-tool.ts
│       ├── upload-img-tool.ts
│       ├── permanent-media-tool.ts
│       ├── draft-tool.ts
│       └── publish-tool.ts
├── auth/                # 認證管理
│   └── auth-manager.ts
├── wechat/              # 微信 API 客戶端
│   └── api-client.ts
├── storage/             # 數據存儲
│   └── storage-manager.ts
└── utils/               # 工具函數
    ├── logger.ts
    └── db-init.ts

配置說明

環境變量

創建 .env 文件：

# 開發模式（可選）
NODE_ENV=development

# 調試模式（可選）
DEBUG=true

# 跨域來源白名單（強烈建議生產環境設置）
CORS_ORIGIN=https://your-domain.com,https://another-domain.com

# 開啟敏感字段加密（設置後啟用 AES 加密存儲）
WECHAT_MCP_SECRET_KEY=your-strong-secret-key

# 數據庫路徑（可選，默認為 ./data/wechat-mcp.db）
DB_PATH=./data/wechat-mcp.db

微信公眾號配置

1. 登錄微信公眾平臺。
2. 進入「開發」->「基本配置」。
3. 獲取 AppID 和 AppSecret。
4. 使用 wechat_auth 工具進行配置。

🔧 技術細節

技術棧

開發指南

開發模式

# 安裝依賴
npm install

# 構建項目
npm run build

# 本地測試 CLI
node dist/src/cli.js mcp -a test_app_id -s test_app_secret

# 類型檢查
npm run check

# 代碼檢查
npm run lint

構建和發佈

# 構建項目
npm run build

# 本地測試包
npm pack

# 發佈到 npm
npm publish

測試

# 運行測試
npm test

# 測試 CLI 功能
node dist/src/cli.js --help

🔒 安全說明

• 加密存儲：設置 WECHAT_MCP_SECRET_KEY 後，app_secret/token/encoding_aes_key/access_token 以加密形式持久化（帶 enc: 前綴標識）。
• 日誌脫敏：錯誤日誌僅記錄狀態碼或消息，避免洩露響應體與敏感信息。
• 跨域白名單：生產環境務必設置 CORS_ORIGIN 為精確域名列表，避免 *。
• 參數校驗：工具參數使用 Zod 校驗，降低不當輸入風險。
• 切勿提交密鑰：不要將 AppSecret、Token 等放入代碼倉庫或構建產物。

🤝 貢獻指南

1. Fork 本項目。
2. 創建特性分支 (git checkout -b feature/AmazingFeature)。
3. 提交更改 (git commit -m 'Add some AmazingFeature')。
4. 推送到分支 (git push origin feature/AmazingFeature)。
5. 開啟 Pull Request。

📄 許可證

本項目採用 MIT 許可證。詳見 LICENSE 文件。

🆘 支持

如果您遇到問題或有建議，請：

1. 查看 Issues 頁面。
2. 創建新的 Issue。
3. 聯繫項目維護者: xwang152-jack xwang152@163.com。

⚠️ 重要提示

本項目僅供學習和開發使用，請遵守微信公眾平臺的使用條款和相關法律法規。