📱 微信公众号自动发布 MCP 服务
📖 目录
🎯 项目概述
这是一个独立的MCP（Model Context Protocol）服务，专门用于微信公众号文章的自动发布。支持任何兼容MCP协议的AI工具调用，包括Claude Desktop、Cursor、Continue等。
🎉 最新更新：已修复MCP SDK兼容性问题，支持最新版本的Claude Desktop和Cursor！
✨ 核心特性
- 🚀 即插即用：标准MCP协议，一键集成到任何AI工具
- 📝 智能转换：自动将Markdown转换为微信公众号优化HTML
- 🖼️ 封面处理：自动上传和处理封面图片
- 👀 预览模式：支持预览和正式发布两种模式
- 📊 状态查询：实时查询文章发布状态和数据统计
- 🔧 错误处理：完善的错误提示和解决建议
- 📱 移动优化：针对微信公众号移动端阅读体验优化
📦 安装
注意：目前该包尚未发布到npm registry，请使用源码安装方式。
方式一：源码安装（推荐）
# 1. 克隆仓库
git clone https://github.com/your-username/wechat-publisher-mcp.git
cd wechat-publisher-mcp
# 2. 安装依赖
npm install
# 3. 配置微信公众号密钥
# ⚠️ 重要安全提示：请勿将真实的AppID和AppSecret提交到代码仓库！
cp examples/wechat-config.example.js examples/wechat-config.js
# 编辑 examples/wechat-config.js，填入您的真实密钥
# 4. 创建全局链接
npm link
# 5. 验证安装
wechat-publisher-mcp --help
安全配置说明
⚠️ 重要：为了保护您的微信公众号安全，请务必正确配置密钥！
- 复制配置示例文件：
cp examples/wechat-config.example.js examples/wechat-config.js
- 编辑配置文件，填入您的真实密钥：
// examples/wechat-config.js
export const wechatConfig = {
appId: 'your_real_appid_here', // 替换为您的真实AppID
appSecret: 'your_real_appsecret_here' // 替换为您的真实AppSecret
};
- 在代码中引用配置：
import { wechatConfig } from './examples/wechat-config.js';
const { appId, appSecret } = wechatConfig;
- 确保配置文件不被提交：
examples/wechat-config.js已添加到.gitignore- 只有示例文件
examples/wechat-config.example.js会被提交到仓库
方式二：直接运行
如果不想全局安装，可以直接运行：
# 克隆并安装依赖
git clone https://github.com/your-username/wechat-publisher-mcp.git
cd wechat-publisher-mcp
npm install
# 直接运行
node src/server.js
系统要求
- Node.js: v18.0.0 或更高版本
- npm: v8.0.0 或更高版本
- 操作系统: macOS, Linux, Windows
验证安装
安装完成后，运行以下命令验证：
# 检查命令是否可用
which wechat-publisher-mcp
# 查看版本信息
wechat-publisher-mcp --version
# 查看帮助信息
wechat-publisher-mcp --help
🔧 配置
1. 微信公众号配置
在微信公众平台完成以下配置：
-
获取AppID和AppSecret：
- 登录 微信公众平台
- 进入 "开发" → "基本配置"
- 记录AppID和AppSecret
-
配置IP白名单：
- 在 "开发" → "基本配置" → "IP白名单"
- 添加服务器IP地址
-
开通发布权限：
- 确保公众号已认证
- 确保具有群发消息权限
2. MCP 客户端配置
Claude Desktop 配置
macOS 配置路径：
~/Library/Application Support/Claude/claude_desktop_config.json
Windows 配置路径：
%APPDATA%\Claude\claude_desktop_config.json
Linux 配置路径：
~/.config/Claude/claude_desktop_config.json
配置内容：
{
"mcpServers": {
"wechat-publisher": {
"command": "wechat-publisher-mcp",
"args": [],
"env": {
"LOG_LEVEL": "INFO"
}
}
}
}
如果使用绝对路径（推荐）：
{
"mcpServers": {
"wechat-publisher": {
"command": "/path/to/your/node",
"args": ["/path/to/wechat-publisher-mcp/src/server.js"]
}
}
}
Cursor 配置
- 打开Cursor设置（
Cmd+,或Ctrl+,） - 搜索"MCP"找到配置选项
- 添加以下配置：
方式一：使用全局命令
{
"mcpServers": {
"wechat-publisher": {
"command": "wechat-publisher-mcp",
"args": []
}
}
}
方式二：使用绝对路径（推荐）
{
"mcpServers": {
"wechat-publisher": {
"command": "/Users/your-username/.nvm/versions/node/v18.20.8/bin/wechat-publisher-mcp",
"args": []
}
}
}
方式三：使用Node.js直接启动（最稳定）
{
"mcpServers": {
"wechat-publisher": {
"command": "/Users/your-username/.nvm/versions/node/v18.20.8/bin/node",
"args": ["/path/to/wechat-publisher-mcp/src/server.js"]
}
}
}
Continue 配置
在Continue的配置文件中添加：
{
"mcpServers": {
"wechat-publisher": {
"command": "wechat-publisher-mcp",
"args": []
}
}
}
配置验证
配置完成后：
- 重启AI工具（Claude Desktop/Cursor等）
- 等待服务初始化（通常需要几秒钟）
- 验证连接：在AI对话中输入"请列出可用的工具"
- 查看状态：MCP服务图标应显示为绿色
故障排除
如果MCP服务图标显示黄色或红色：
-
检查命令路径：
which wechat-publisher-mcp -
使用绝对路径：将上述命令返回的完整路径用于配置
-
检查Node.js版本：
node --version # 应该 >= v18.0.0 -
查看错误日志：打开AI工具的开发者工具查看Console错误
-
手动测试：在终端中直接运行命令验证
wechat-publisher-mcp
🚀 新手快速开始
第一步：环境准备
-
检查Node.js版本
node --version # 需要 >= v18.0.0如果版本过低，请访问 Node.js官网 下载最新版本。
-
检查npm版本
npm --version # 需要 >= v8.0.0
第二步：安装项目
# 1. 克隆项目到本地
git clone https://github.com/your-username/wechat-publisher-mcp.git
cd wechat-publisher-mcp
# 2. 安装依赖
npm install
# 3. 创建全局链接
npm link
# 4. 验证安装
wechat-publisher-mcp --help
第三步：获取微信公众号配置
-
登录微信公众平台
- 访问 https://mp.weixin.qq.com
- 使用管理员账号登录
-
获取AppID和AppSecret
- 进入"开发" → "基本配置"
- 复制保存AppID和AppSecret
-
配置IP白名单
- 在"基本配置"页面找到"IP白名单"
- 添加你的服务器IP地址（可以先添加
0.0.0.0/0用于测试）
第四步：配置AI工具
如果你使用Claude Desktop：
-
找到配置文件
# macOS open "~/Library/Application Support/Claude/" # Windows # 打开 %APPDATA%\Claude\ # Linux # 打开 ~/.config/Claude/ -
编辑claude_desktop_config.json
{ "mcpServers": { "wechat-publisher": { "command": "wechat-publisher-mcp", "args": [] } } } -
重启Claude Desktop
如果你使用Cursor：
-
打开Cursor设置
- 按
Cmd+,(Mac) 或Ctrl+,(Windows/Linux)
- 按
-
搜索MCP配置
- 在设置中搜索"MCP"
-
添加服务配置
# 首先获取你的命令路径 which wechat-publisher-mcp然后使用返回的完整路径配置：
{ "mcpServers": { "wechat-publisher": { "command": "/your/full/path/to/wechat-publisher-mcp", "args": [] } } } -
重启Cursor
第五步：测试连接
-
验证MCP服务状态
- 在AI工具中，MCP服务图标应显示为绿色
- 如果显示黄色或红色，请查看故障排除部分
-
测试工具可用性 在AI对话中输入：
请列出可用的工具你应该能看到以下工具：
wechat_publish_article- 发布文章wechat_query_status- 查询状态
第六步：发布第一篇文章
在AI工具中输入以下内容（替换为你的实际信息）：
请帮我发布一篇测试文章到微信公众号：
标题：我的第一篇AI发布文章
作者：你的名字
AppID：你的微信公众号AppID
AppSecret：你的微信公众号AppSecret
预览模式：true
预览用户OpenID：你的OpenID（可选，用于预览）
内容：
# 欢迎使用微信公众号自动发布工具
这是一篇测试文章，用于验证MCP服务是否正常工作。
## 功能特点
- ✅ 支持Markdown格式
- ✅ 自动转换为微信HTML
- ✅ 支持预览和正式发布
- ✅ 实时状态查询
**测试成功！** 🎉
常见问题解决
Q: MCP服务图标显示黄色怎么办？
A: 这通常表示路径问题，请使用 which wechat-publisher-mcp 获取完整路径，然后在配置中使用绝对路径。
Q: 提示"access_token invalid"怎么办？ A: 检查AppID和AppSecret是否正确，确保在微信公众平台的"基本配置"中获取。
Q: 提示IP不在白名单怎么办？ A: 在微信公众平台的"基本配置" → "IP白名单"中添加你的服务器IP。
Q: 如何获取预览用户的OpenID？ A: 可以通过微信公众号的用户管理功能获取，或者先不使用预览模式直接发布。
🚀 使用方法
基础发布
// 在AI工具中直接描述需求
"请帮我发布一篇文章到微信公众号，标题是'AI赋能内容创作'，作者是'张三'，内容是以下Markdown..."
预览模式
"请先预览这篇文章，预览用户OpenID是 'xxx'，然后再决定是否正式发布"
状态查询
"查询刚才发布的文章状态，消息ID是 '12345'"
🛠️ API 工具
1. wechat_publish_article
发布或预览文章到微信公众号。
参数：
| 参数名 | 类型 | 必需 | 说明 |
|---|---|---|---|
| title | string | ✅ | 文章标题（最大64字符） |
| content | string | ✅ | 文章内容（Markdown格式） |
| appId | string | ✅ | 微信公众号AppID |
| appSecret | string | ✅ | 微信公众号AppSecret |
| author | string | ❌ | 作者名称（最大8字符） |
| coverImagePath | string | ❌ | 封面图片路径 |
| previewMode | boolean | ❌ | 是否预览模式（默认false） |
| previewOpenId | string | ❌ | 预览用户OpenID（预览模式必需） |
返回值：
{
"success": true,
"publishId": "2247483647",
"msgId": "1000000001",
"articleUrl": "https://mp.weixin.qq.com/s?__biz=...",
"mediaId": "media_id_here"
}
2. wechat_query_status
查询文章发布状态和统计数据。
参数：
| 参数名 | 类型 | 必需 | 说明 |
|---|---|---|---|
| msgId | string | ✅ | 消息ID |
| appId | string | ✅ | 微信公众号AppID |
| appSecret | string | ✅ | 微信公众号AppSecret |
返回值：
{
"article_id": "123456",
"publish_status": 1,
"article_detail": {
"title": "文章标题",
"author": "作者",
"publish_time": 1634567890,
"url": "https://mp.weixin.qq.com/s?...",
"stat_info": {
"read_num": 1000,
"like_num": 50,
"comment_num": 10,
"share_num": 20
}
}
}
📋 示例
完整发布流程
# 示例：发布技术文章
## 步骤1：准备内容
将文章写成Markdown格式，包含代码块、图片等。
## 步骤2：准备封面图
准备一张封面图片，支持PNG、JPG、JPEG格式，建议尺寸900x500px。
## 步骤3：发布文章
在AI工具中说："请发布这篇文章到微信公众号"，并提供：
- 标题：🔥 AI赋能Chrome扩展开发：从PromptX到功能实现的全流程实战教程
- 作者：郑伟 | PromptX技术
- AppID：your_wechat_appid_here（请替换为您的真实AppID）
- AppSecret：your_wechat_appsecret_here（请替换为您的真实AppSecret）
- 封面图：./cover.png
- 内容：[Markdown内容]
## 步骤4：查询状态
发布后使用返回的msgId查询文章状态和数据。
自然语言示例
用户："帮我把这篇关于Chrome扩展开发的教程发布到微信公众号，标题叫'AI赋能Chrome扩展开发实战教程'，作者署名'郑伟'，先预览给我看看效果"
AI会自动：
1. 解析用户需求
2. 转换Markdown为微信HTML
3. 上传封面图（如果提供）
4. 发送预览消息
5. 返回预览结果和链接
🔧 高级配置
环境变量
| 变量名 | 默认值 | 说明 |
|---|---|---|
| LOG_LEVEL | INFO | 日志级别（ERROR/WARN/INFO/DEBUG） |
| NO_COLOR | 0 | 禁用彩色输出（设为1禁用） |
| NODE_ENV | development | 运行环境 |
启动参数
# 调试模式启动
LOG_LEVEL=DEBUG wechat-publisher-mcp
# 生产模式启动
NODE_ENV=production wechat-publisher-mcp
🐛 故障排除
MCP连接问题
1. MCP服务图标显示黄色或红色
症状：AI工具中MCP服务状态异常
解决方案：
-
检查命令路径
which wechat-publisher-mcp -
使用绝对路径配置
{ "mcpServers": { "wechat-publisher": { "command": "/Users/username/.nvm/versions/node/v18.20.8/bin/wechat-publisher-mcp", "args": [] } } } -
使用Node.js直接启动
{ "mcpServers": { "wechat-publisher": { "command": "/Users/username/.nvm/versions/node/v18.20.8/bin/node", "args": ["/path/to/wechat-publisher-mcp/src/server.js"] } } }
2. ERR_PACKAGE_PATH_NOT_EXPORTED 错误
症状：启动时报模块导入错误
解决方案：
# 重新安装依赖
cd wechat-publisher-mcp
npm install
# 检查Node.js版本
node --version # 确保 >= v18.0.0
3. 命令未找到错误
症状：command not found: wechat-publisher-mcp
解决方案：
# 重新创建全局链接
npm unlink -g wechat-publisher-mcp
npm link
# 或者检查PATH环境变量
echo $PATH
微信API错误
1. IP白名单错误
错误：invalid ip xxx, not in whitelist
解决：在微信公众平台添加服务器IP到白名单
详细步骤：
- 登录微信公众平台
- 进入"开发" → "基本配置"
- 找到"IP白名单"设置
- 添加你的公网IP地址
- 如果不确定IP，可以临时添加
0.0.0.0/0（仅用于测试）
2. access_token错误
错误：access_token invalid
解决：检查AppID和AppSecret是否正确
检查清单：
- AppID格式正确（以wx开头）
- AppSecret长度为32位
- 没有多余的空格或换行符
- 公众号类型支持API调用
3. 封面图上传失败
错误：图片上传失败
解决：检查图片格式（PNG/JPG）和大小（<1MB）
图片要求：
- 格式：PNG、JPG、JPEG
- 大小：< 1MB
- 尺寸：建议 900x500px
- 路径：使用绝对路径或相对于项目根目录的路径
4. 预览失败
错误：预览用户不存在
解决：确认previewOpenId是否正确，用户是否关注公众号
获取OpenID方法：
- 在微信公众平台的"用户管理"中查看
- 通过微信网页授权获取
- 使用微信开发者工具测试
权限和认证问题
1. 公众号权限不足
错误：no privilege to write this kind of message
解决：确保公众号已认证且具有群发权限
2. 接口调用次数限制
错误：api minute-quota reach limit
解决：等待一分钟后重试，或优化调用频率
环境和依赖问题
1. Node.js版本过低
错误：SyntaxError: Unexpected token
解决：升级Node.js到v18.0.0或更高版本
2. 依赖安装失败
错误：npm install失败
解决：清理缓存后重新安装
npm cache clean --force
rm -rf node_modules package-lock.json
npm install
调试模式
启用调试模式查看详细日志：
# 方式一：环境变量
LOG_LEVEL=DEBUG wechat-publisher-mcp
# 方式二：在配置中添加
{
"mcpServers": {
"wechat-publisher": {
"command": "wechat-publisher-mcp",
"args": [],
"env": {
"LOG_LEVEL": "DEBUG",
"DEBUG": "true"
}
}
}
}
获取帮助
如果以上方法都无法解决问题：
- 查看详细日志：启用DEBUG模式
- 检查网络连接：确保能访问微信API
- 提交Issue：在GitHub仓库提交详细的错误信息
- 社区求助：在相关技术社区寻求帮助
提交Issue时请包含：
- 操作系统和版本
- Node.js版本
- 错误的完整日志
- 复现步骤
- 配置文件（隐藏敏感信息）
🧪 测试
# 运行单元测试
npm test
# 运行集成测试
npm run test:integration
# 运行代码覆盖率测试
npm run test:coverage
🤝 贡献
欢迎提交Issue和Pull Request！
- Fork本仓库
- 创建特性分支：
git checkout -b feature/amazing-feature - 提交更改：
git commit -m 'Add amazing feature' - 推送分支：
git push origin feature/amazing-feature - 提交Pull Request
📄 许可证
本项目采用 MIT 许可证 - 查看 LICENSE 文件了解详情。
🔗 相关链接
官方文档
AI工具配置
开发资源
社区和支持
🙏 致谢
感谢以下项目和社区的支持：
核心技术
- Model Context Protocol - 提供了强大的AI工具协议支持
- 微信公众平台 - 提供了完善的API接口
- Node.js社区 - 提供了优秀的运行时环境
灵感来源
- PromptX项目 - 原始灵感和技术架构参考
- Claude Desktop - MCP协议的先驱实现
- Cursor - 优秀的AI编程工具
开源社区
- 所有提交Issue和PR的贡献者
- 微信开发者社区的技术分享
- MCP协议的早期采用者和反馈者
特别感谢
- 郑伟 - 项目发起人和主要维护者
- PromptX团队 - 技术指导和架构设计
- 所有测试用户 - 提供了宝贵的使用反馈
📢 如果这个项目对您有帮助，请给我们一个⭐！