微信公众号 MCP 服务

一个为 AI 应用提供微信公众号 API 集成的 MCP (Model Context Protocol) 服务项目。

作者: xwang152-jack xwang152@163.com
更新日期: 2025年11月20日

🚀 项目概述

本项目基于 MCP 协议，为 AI 应用（如 Claude Desktop、Cursor、Trae AI 等）提供微信公众号 API 的无缝集成。通过标准化的工具接口，AI 应用可以轻松地管理微信公众号的素材、草稿、发布等功能。

当前版本：v1.1.0（查看 CHANGELOG 与 Release 说明）

✨ 核心功能

🔐 认证管理: 安全管理微信公众号 AppID、AppSecret 和 Access Token
📁 素材管理: 上传、获取、管理临时和永久素材
📝 草稿管理: 创建、编辑、管理图文草稿
📢 发布管理: 发布草稿到微信公众号
💾 本地存储: 使用 SQLite 本地存储配置和数据
🔧 MCP 集成: 完全兼容 MCP 协议标准
🛡️ 安全增强（v1.1.0）: 支持敏感字段加密存储与日志脱敏，跨域来源白名单配置

🛠️ 技术栈

运行时: Node.js 18+
语言: TypeScript
协议: MCP (Model Context Protocol)
数据库: SQLite
HTTP 客户端: Axios
参数验证: Zod
构建工具: Vite

📦 快速开始

方式一：使用 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），设置即启用

🔧 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

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

🧪 开发指南

开发模式

# 安装依赖
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

启动 Web 界面

项目提供了 Web 管理界面，可以通过以下方式启动：

方式一：同时启动前端和后端（推荐）

npm run dev:all

这将同时启动：

后端 API 服务器（运行在 http://localhost:3001）
前端开发服务器（运行在 http://localhost:5173，Vite 默认端口）

方式二：分别启动

# 终端 1：启动后端 API 服务器
npm run dev:api

# 终端 2：启动前端开发服务器
npm run dev:web

启动后，在浏览器中访问 http://localhost:5173 即可使用 Web 界面。

注意：前端开发服务器会自动代理 /api 请求到后端服务器（http://localhost:3001）。

构建和发布

# 构建项目
npm run build

# 本地测试包
npm pack

# 发布到 npm
npm publish

测试

# 运行测试
npm test

# 测试 CLI 功能
node dist/src/cli.js --help

📝 配置说明

环境变量

创建 .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

微信公众号配置

登录微信公众平台
进入「开发」->「基本配置」
获取 AppID 和 AppSecret
配置 IP 白名单（重要！）
- 在「基本配置」页面找到「IP白名单」设置
- 添加服务器实际使用的 IP 地址
- 如果遇到 invalid ip, not in whitelist 错误，错误信息中会显示需要添加的 IP
- 添加后等待几分钟生效
使用 wechat_auth 工具进行配置

🔒 安全说明

加密存储：设置 WECHAT_MCP_SECRET_KEY 后，app_secret/token/encoding_aes_key/access_token 以加密形式持久化（带 enc: 前缀标识）
日志脱敏：错误日志仅记录状态码或消息，避免泄露响应体与敏感信息
跨域白名单：生产环境务必设置 CORS_ORIGIN 为精确域名列表，避免 *
参数校验：工具参数使用 Zod 校验，降低不当输入风险
切勿提交密钥：不要将 AppSecret、Token 等放入代码仓库或构建产物

🤝 贡献指南

Fork 本项目
创建特性分支 (git checkout -b feature/AmazingFeature)
提交更改 (git commit -m 'Add some AmazingFeature')
推送到分支 (git push origin feature/AmazingFeature)
开启 Pull Request

📄 许可证

本项目采用 MIT 许可证。详见 LICENSE 文件。

🆘 支持

如果您遇到问题或有建议，请：

查看 Issues 页面
创建新的 Issue
联系项目维护者: xwang152-jack xwang152@163.com

🙏 致谢

Model Context Protocol - MCP 协议标准
微信公众平台 - 微信公众号 API
Anthropic - Claude Desktop MCP 支持

注意: 本项目仅供学习和开发使用，请遵守微信公众平台的使用条款和相关法律法规。

Name		Name	Last commit message	Last commit date
Latest commit History 21 Commits
.cursor		.cursor
api		api
data		data
doc		doc
public		public
scripts		scripts
src		src
.gitignore		.gitignore
.npmignore		.npmignore
ARCHITECTURE.md		ARCHITECTURE.md
CHANGELOG.md		CHANGELOG.md
LICENSE		LICENSE
README.md		README.md
RELEASE_NOTES_v1.1.0.md		RELEASE_NOTES_v1.1.0.md
eslint.config.js		eslint.config.js
index.html		index.html
nodemon.json		nodemon.json
package-lock.json		package-lock.json
package.json		package.json
postcss.config.js		postcss.config.js
tailwind.config.js		tailwind.config.js
test-tools.js		test-tools.js
tsconfig.json		tsconfig.json
tsconfig.prod.json		tsconfig.prod.json
vercel.json		vercel.json
vite.config.ts		vite.config.ts

License

crafthm/wechat-official-account-mcp

Folders and files

Latest commit

History

Repository files navigation

微信公众号 MCP 服务

🚀 项目概述

✨ 核心功能

🛠️ 技术栈

📦 快速开始

方式一：使用 npx（推荐）

方式二：全局安装

方式三：本地开发

CLI 参数说明

🔧 MCP 工具列表

1. 认证工具 (wechat_auth)

2. 素材上传工具 (wechat_media_upload)

3. 图文消息图片上传工具 (wechat_upload_img)

4. 永久素材工具 (wechat_permanent_media)

5. 草稿管理工具 (wechat_draft)

6. 发布工具 (wechat_publish)

📁 项目结构

🔗 在 AI 应用中使用

Claude Desktop

Cursor / Trae AI

🧪 开发指南

开发模式

启动 Web 界面

构建和发布

测试

📝 配置说明

环境变量

微信公众号配置

🔒 安全说明

🤝 贡献指南

📄 许可证

🆘 支持

🙏 致谢

About

Resources

License

Uh oh!

Stars

Watchers

Forks

Releases

Packages 0

Languages

1. 认证工具 (`wechat_auth`)

2. 素材上传工具 (`wechat_media_upload`)

3. 图文消息图片上传工具 (`wechat_upload_img`)

4. 永久素材工具 (`wechat_permanent_media`)

5. 草稿管理工具 (`wechat_draft`)

6. 发布工具 (`wechat_publish`)

Packages