npm package: @lanyijianke/wechat-official-account-mcp
Description: 微信公众号MCP服务器 - 支持Markdown文章推送到草稿箱，自动处理图片上传
Author: lanyijianke
Latest version: 4.2.2

# 微信公众号 MCP 服务器

<div align="center">
  <img src="https://img.shields.io/badge/WeChat-Official-green" alt="WeChat Official Account">
  <img src="https://img.shields.io/badge/MCP-Model%20Context%20Protocol-blue" alt="MCP">
  <img src="https://img.shields.io/badge/TypeScript-007ACC?logo=typescript&logoColor=white" alt="TypeScript">
  <img src="https://img.shields.io/badge/License-MIT-yellow.svg" alt="MIT License">
  <img src="https://img.shields.io/npm/v/@lanyijianke/wechat-official-account-mcp" alt="npm version">
</div>

## 📣 最新更新（v4.1.1）

### 🆕 新增功能
- 🎉 **图片消息功能**！支持创建类似小红书笔记格式的短图文内容
- 📸 支持1-9张图片的图片消息，最多1000字描述文字
- 🎨 优化的移动端显示效果，圆角图片和现代化UI设计

### 🔧 功能优化
- ✅ 全面重构代码架构，提高稳定性和性能
- ✅ 优化图片处理算法，支持更多图片格式和复杂路径处理
- ✅ 增强错误处理机制，提供更详细的调试信息
- ✅ 改进文件查找逻辑，支持智能文件名匹配
- ✅ 完善 TypeScript 类型定义，提升开发体验

### 🐛 问题修复
- 🔧 修复相对路径图片处理问题
- 🔧 优化网络图片上传稳定性
- 🔧 改进错误信息显示格式

## 📖 项目简介

微信公众号 MCP 服务器是一个基于 Model Context Protocol (MCP) 的工具，专为微信公众号内容管理设计。它支持将 Markdown 文章推送到微信公众号草稿箱，自动处理图片上传，并提供丰富的草稿管理功能。

### ✨ 核心特性

- 🚀 **Markdown 支持**: 自动将 Markdown 转换为微信公众号兼容的 HTML 格式
- 🖼️ **智能图片处理**: 自动上传本地图片和网络图片到微信素材库
- 📸 **图片消息**: 支持创建1-9张图片的图文消息，类似小红书笔记格式
- 📱 **完美适配**: 针对微信公众号优化的样式和排版
- 🔧 **MCP 集成**: 无缝集成到支持 MCP 的 AI 工具中（Claude、Cursor等）
- 📋 **草稿管理**: 完整的草稿箱管理功能（查看、删除、批量操作）
- 🖥️ **命令行支持**: 支持命令行直接操作，方便自动化
- 🔐 **安全配置**: 支持环境变量配置，保护敏感信息
- 🎯 **智能文件查找**: 支持模糊文件名匹配，无需完整路径

## 🎯 主要功能

### 📝 文章推送

- 推送 Markdown 文章到草稿箱
- 推送 HTML 文章到草稿箱
- 从文件推送 Markdown 文章（支持相对路径图片）
- 📸 **创建图片消息**（类似小红书笔记格式，1-9张图片）

### 🖼️ 图片处理

- 自动上传本地图片到微信素材库
- 支持网络图片上传
- 智能路径解析（相对路径/绝对路径）
- 支持多种图片格式（JPG、PNG、GIF、WebP、BMP）

### 📋 草稿管理

- 获取草稿箱文章列表
- 查看草稿文章详情
- 删除单个草稿
- 批量删除所有草稿

### 🔧 工具功能

- Markdown 转 HTML 转换
- 测试微信 API 连接
- 图片上传工具

## 🚀 快速开始

### 安装

```bash
# 使用 npm 安装
npm install -g @lanyijianke/wechat-official-account-mcp

# 或使用 npx 直接运行
npx @lanyijianke/wechat-official-account-mcp
```

### 配置

#### 方式一：环境变量配置（推荐）

```bash
export WECHAT_APP_ID="your_app_id"
export WECHAT_APP_SECRET="your_app_secret"
export WECHAT_DEFAULT_AUTHOR="默认作者名"
export WECHAT_NEED_OPEN_COMMENT="true"
export WECHAT_ONLY_FANS_CAN_COMMENT="true"
```

#### 方式二：配置文件

复制 `config.example.json` 为 `config.json` 并填写配置：

```json
{
  "wechat": {
    "appId": "your_app_id",
    "appSecret": "your_app_secret",
    "defaultAuthor": "默认作者名",
    "needOpenComment": true,
    "onlyFansCanComment": true
  }
}
```

### 获取微信公众号配置

1. 登录 [微信公众平台](https://mp.weixin.qq.com)
2. 进入"开发" → "基本配置"
3. 获取 AppID 和 AppSecret

## 💻 使用方法

### MCP 集成

将以下配置添加到支持 MCP 的 AI 工具配置中（如 Claude Desktop）：

```json
{
  "mcpServers": {
    "wechat-official-account-mcp": {
      "command": "npx",
      "args": [
        "@lanyijianke/wechat-official-account-mcp@latest"
      ],
      "env": {
        "WECHAT_APP_ID": "您的微信公众号AppID",
        "WECHAT_APP_SECRET": "您的微信公众号AppSecret",
        "WECHAT_DEFAULT_AUTHOR": "默认作者名称",
        "WECHAT_NEED_OPEN_COMMENT": "true",
        "WECHAT_ONLY_FANS_CAN_COMMENT": "true"
      }
    }
  }
}
```

### 命令行使用

#### 推送 Markdown 文章

```bash
# 基本用法
wechat-mcp push-markdown --input "article.md" --title "文章标题"

# 或使用简单文件名（自动查找）
wechat-mcp push-markdown --input "article" --title "文章标题"

# 完整参数
wechat-mcp push-markdown \
  --input "article.md" \
  --title "文章标题" \
  --brief "文章摘要" \
  --source-url "https://example.com"
```

**文件查找说明：**
- 可以只提供文件名，无需完整路径
- 系统会自动在项目目录中查找匹配的文件
- 可以省略`.md`扩展名

#### 其他命令

```bash
# 测试连接
wechat-mcp test-connection

# 获取草稿列表
wechat-mcp get-drafts

# 批量删除所有草稿（危险操作）
wechat-mcp delete-all-drafts --confirm
```

## 🔧 MCP 工具说明

本项目提供 **10个核心工具**，涵盖文章推送、图片处理、草稿管理等完整功能：

### 文章推送工具

#### `push-markdown-file-to-draft`

从文件推送 Markdown 文章到草稿箱

**参数：**

- `filePath` (string): Markdown 文件路径或文件名
- `title` (string): 文章标题
- `digest` (string, 可选): 文章摘要
- `sourceUrl` (string, 可选): 原文链接

**特性：**

- **智能文件查找**: 可以只提供文件名，系统会自动在项目目录中查找匹配的文件
- **支持扩展名省略**: 可以省略 `.md`扩展名，如 `article`会自动匹配 `article.md`
- **优先已知目录**: 会优先检查常见目录如 `test文章`、`docs`、`content`等

### 内容处理工具

#### `markdown-to-html`

将 Markdown 内容转换为 HTML 格式

**参数：**

- `markdown` (string): Markdown 内容
- `processImages` (boolean, 可选): 是否处理图片上传（默认 true）

#### `create-image-message` 🆕

创建图片消息到草稿箱（类似小红书笔记格式）

**参数：**

- `title` (string): 图片消息标题
- `description` (string): 描述文字（最多1000字）
- `imageUrls` (string[]): 图片URL数组（1-9张图片）
- `digest` (string, 可选): 摘要（如果不提供则自动生成）
- `sourceUrl` (string, 可选): 原文链接

#### `upload-image`

上传图片到微信素材库

**参数：**

- `imageUrl` (string): 图片 URL 地址或本地路径
- `permanent` (boolean, 可选): 是否上传为永久素材（默认 true）

### 草稿管理工具

#### `get-draft-list`

获取草稿箱文章列表

**参数：**

- `offset` (number, 可选): 偏移量（默认 0）
- `count` (number, 可选): 获取数量（默认 20，最大 20）

#### `get-draft-detail`

获取草稿文章详情

**参数：**

- `mediaId` (string): 文章媒体 ID

#### `delete-draft`

删除草稿文章

**参数：**

- `mediaId` (string): 要删除的文章媒体 ID

#### `delete-all-drafts`

批量删除所有草稿文章

**参数：**

- `confirm` (boolean, 可选): 确认删除所有草稿（必须设置为 true）

### 工具功能

#### `test-connection`

测试微信公众号 API 连接

**参数：** 无

## 🎨 样式特性

### Markdown 转换优化

- **中文字体**: 优化的中文字体栈，确保最佳显示效果
- **段落样式**: 合适的行高和字间距，提升阅读体验
- **标题分层**: H1-H3 标题的差异化样式设计
- **引用块**: 精美的左边框引用样式
- **代码块**: 支持内联代码和代码块的语法高亮
- **列表样式**: 自定义的列表项目符号和编号
- **图片处理**: 自动添加圆角和居中对齐

### 图片处理特性

- **自动上传**: 本地图片自动上传到微信素材库
- **路径解析**: 智能处理相对路径和绝对路径
- **格式支持**: 支持 JPG、PNG、GIF、WebP、BMP 格式
- **错误处理**: 上传失败时提供明确的错误信息

## 📋 示例

### 图片消息示例 🆕

使用 `create-image-message` 工具创建类似小红书的图片笔记：

```json
{
  "title": "🌸 春日赏花记",
  "description": "今天去公园赏花，春天真是太美了！🌸\n\n粉色的樱花正在盛开，微风吹过，花瓣飘落，像下雪一样浪漫。\n\n和朋友一起拍了很多照片，记录下这美好的时刻。\n\n春天的阳光温暖而不刺眼，正是出游的好时候！",
  "imageUrls": [
    "https://example.com/cherry-blossom-1.jpg",
    "https://example.com/cherry-blossom-2.jpg",
    "https://example.com/cherry-blossom-3.jpg"
  ],
  "digest": "春日赏花的美好时光，记录樱花盛开的浪漫时刻"
}
```

**生成效果：**
- 📱 移动端优化的布局
- 🖼️ 圆角图片，带阴影效果
- 📝 清晰的文字排版
- 🎨 现代化的视觉设计

### 推送 Markdown 文章示例

```markdown
# 我的第一篇文章

这是一篇测试文章，包含：

## 功能特色

- **粗体文字**
- *斜体文字*
- `内联代码`

### 代码示例

```javascript
console.log("Hello WeChat!");
```

### 引用

> 这是一个引用块的示例

### 图片

```

### 使用 MCP 工具推送

```javascript
// 在支持 MCP 的 AI 工具中使用
await pushToDraft({
  title: "我的第一篇文章",
  content: markdownContent,
  author: "张三",
  isMarkdown: true,
  needOpenComment: true
});
```

## 🔐 安全配置

### 环境变量保护

为了保护敏感信息，建议使用环境变量配置：

```bash
# .env 文件
WECHAT_APP_ID=your_app_id
WECHAT_APP_SECRET=your_app_secret
WECHAT_DEFAULT_AUTHOR=默认作者
```

### MCP 配置安全

在 MCP 配置中使用环境变量：

```json
{
  "mcpServers": {
    "wechat-official-account-mcp": {
      "command": "npx",
      "args": [
        "@lanyijianke/wechat-official-account-mcp@latest"
      ],
      "env": {
        "WECHAT_APP_ID": "${WECHAT_APP_ID}",
        "WECHAT_APP_SECRET": "${WECHAT_APP_SECRET}",
        "WECHAT_DEFAULT_AUTHOR": "${WECHAT_DEFAULT_AUTHOR}",
        "WECHAT_NEED_OPEN_COMMENT": "${WECHAT_NEED_OPEN_COMMENT}",
        "WECHAT_ONLY_FANS_CAN_COMMENT": "${WECHAT_ONLY_FANS_CAN_COMMENT}"
      }
    }
  }
}
```

## 🐛 常见问题

### Q: 图片上传失败怎么办？

A: 检查以下几点：

1. 确保图片文件存在且路径正确
2. 检查图片格式是否支持（JPG、PNG、GIF、WebP、BMP）
3. 确保网络连接正常
4. 检查微信公众号配置是否正确

### Q: 推送文章失败？

A: 可能的原因：

1. AppID 或 AppSecret 配置错误
2. 微信公众号未认证或权限不足
3. 文章内容包含敏感词汇
4. 缩略图上传失败

### Q: 如何查看详细错误信息？

A: 运行时会在控制台输出详细的错误信息，包括：

- API 响应详情
- 图片上传状态
- 网络请求日志

## 🤝 贡献

欢迎提交 Issue 和 Pull Request！

### 开发环境设置

```bash
# 克隆项目
git clone https://github.com/lanyijianke/wechat-official-account-mcp.git

# 安装依赖
npm install

# 编译项目
npm run build

# 启动开发
npm run dev
```

## 📄 许可证

本项目采用 MIT 许可证。详情请查看 [LICENSE](LICENSE) 文件。

## 📈 项目统计

- **⭐ GitHub Stars**: 持续增长中
- **📦 NPM 下载量**: 每周活跃用户
- **🛠️ 工具数量**: 10个核心功能工具
- **🔧 支持的 AI 工具**: Claude Desktop、Cursor、Continue 等
- **📝 文档完整度**: 100%覆盖所有功能

## 🔗 相关链接

- [📱 微信公众平台](https://mp.weixin.qq.com)
- [🔗 Model Context Protocol](https://github.com/modelcontextprotocol)
- [🚀 项目仓库](https://github.com/lanyijianke/wechat-official-account-mcp)
- [📦 NPM 包](https://www.npmjs.com/package/@lanyijianke/wechat-official-account-mcp)
- [🐛 问题反馈](https://github.com/lanyijianke/wechat-official-account-mcp/issues)
- [💡 功能建议](https://github.com/lanyijianke/wechat-official-account-mcp/discussions)

---

<div align="center">
  <p>如果这个项目对您有帮助，请给一个 ⭐️ Star 支持一下！</p>
</div>