# wechat-post-mcp

**Repository Path**: copy_Soft/wechat-post-mcp

## Basic Information

- **Project Name**: wechat-post-mcp
- **Description**: 这是一个完整的 MCP 服务器项目，用于与微信公众号集成：

三大功能：
📝 post_article - 发布文章到草稿
🚀 publish_article - 发布草稿给粉丝
🖼️ post_image_text - 发布图文内容
- **Primary Language**: NodeJS
- **License**: MIT
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-08-10
- **Last Updated**: 2026-08-10

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# 🎯 WeChat Post MCP Server

一个基于 **Model Context Protocol (MCP)** 的微信公众号发布服务器，允许任何 MCP 客户端（包括 Claude）通过标准 MCP 协议调用微信文章发布功能。

[![Node.js](https://img.shields.io/badge/node.js-v18+-green)](https://nodejs.org/)
[![MCP](https://img.shields.io/badge/MCP-v1.30+-blue)](https://modelcontextprotocol.io/)
[![License](https://img.shields.io/badge/license-ISC-brightgreen)](LICENSE)

## ✨ 核心功能

- 📝 **发布文章** - 将内容发布为微信公众号草稿
- 🚀 **发布内容** - 从草稿发布到所有粉丝
- 🖼️ **图文发布** - 支持多内容项的图文消息发布
- 🔗 **MCP 集成** - 标准 MCP 协议，与任何 MCP 客户端兼容
- 🤖 **Claude 友好** - 可直接集成到 Claude 桌面应用

## 📋 快速开始

### 前置条件

- Node.js >= 18
- npm 或 yarn
- 微信公众号应用凭证（APP_ID 和 APP_SECRET）

### 安装

```bash
# 克隆或下载项目
cd wechat-post-mcp

# 安装依赖
npm install

# 编译 TypeScript
npm run build
```

### 配置

设置微信认证环境变量：

**方法 1：直接导出**
```bash
export WECHAT_APP_ID=your_app_id_here
export WECHAT_APP_SECRET=your_app_secret_here
```

**方法 2：创建 .env 文件**
```bash
cp .env.example .env
# 编辑 .env，填入你的 APP_ID 和 APP_SECRET
```

**.env 文件示例：**
```env
WECHAT_APP_ID=wx1234567890abcdef
WECHAT_APP_SECRET=your_secret_key_here
```

### 运行服务器

**生产环境：**
```bash
npm start
```

**开发环境（带 watch）：**
```bash
npm run dev
```

服务器将通过 stdio 连接启动，等待 MCP 客户端连接。

## 🛠️ API 工具

### 1️⃣ post_article - 发布文章到草稿

将一篇新文章发布为微信公众号草稿。

**参数：**
| 参数 | 类型 | 必需 | 说明 |
|------|------|------|------|
| `title` | string | ✅ | 文章标题 |
| `content` | string | ✅ | 文章内容（HTML 或 Markdown） |
| `author` | string | ❌ | 作者名称 |
| `digest` | string | ❌ | 文章摘要（显示在列表中） |
| `thumb` | string | ❌ | 封面图片 URL（需要是微信 media_id） |
| `show_cover_pic` | boolean | ❌ | 是否显示封面图片（默认: true） |

**返回成功响应：**
```json
{
  "success": true,
  "mediaId": "3T7wPWULLjDf7JtJrlgIKEddqPCM4mOx_xxxxxxx",
  "timestamp": "2024-08-10T22:30:00Z"
}
```

**使用示例：**
```bash
# 通过 MCP 客户端调用
curl -X POST http://localhost:3000/tools/call \
  -H "Content-Type: application/json" \
  -d '{
    "tool": "post_article",
    "arguments": {
      "title": "我的第一篇文章",
      "content": "<p>这是文章正文...</p>",
      "author": "John Doe",
      "digest": "摘要内容"
    }
  }'
```

---

### 2️⃣ publish_article - 发布草稿到粉丝

将已创建的草稿发布到所有粉丝。

**参数：**
| 参数 | 类型 | 必需 | 说明 |
|------|------|------|------|
| `media_id` | string | ✅ | post_article 返回的 mediaId |

**返回成功响应：**
```json
{
  "success": true,
  "msgId": "1234567890123456",
  "timestamp": "2024-08-10T22:35:00Z"
}
```

**使用示例：**
```bash
curl -X POST http://localhost:3000/tools/call \
  -H "Content-Type: application/json" \
  -d '{
    "tool": "publish_article",
    "arguments": {
      "media_id": "3T7wPWULLjDf7JtJrlgIKEddqPCM4mOx_xxxxxxx"
    }
  }'
```

---

### 3️⃣ post_image_text - 发布图文消息

发布包含多个内容项的图文消息。

**参数：**
| 参数 | 类型 | 必需 | 说明 |
|------|------|------|------|
| `items` | array | ✅ | 图文项数组（每项包含以下字段） |
| `items[].title` | string | ✅ | 项目标题 |
| `items[].content` | string | ✅ | 项目 HTML 内容 |
| `items[].author` | string | ❌ | 项目作者 |
| `items[].digest` | string | ❌ | 项目摘要 |
| `items[].thumb` | string | ❌ | 项目缩略图 URL |
| `items[].show_cover_pic` | boolean | ❌ | 显示封面图片（默认: true） |
| `items[].content_source_url` | string | ❌ | 源 URL（原创声明用） |

**返回成功响应：**
```json
{
  "success": true,
  "mediaId": "3T7wPWULLjDf7JtJrlgIKEddqPCM4mOx_xxxxxxx",
  "timestamp": "2024-08-10T22:40:00Z"
}
```

**使用示例：**
```bash
curl -X POST http://localhost:3000/tools/call \
  -H "Content-Type: application/json" \
  -d '{
    "tool": "post_image_text",
    "arguments": {
      "items": [
        {
          "title": "第一条内容",
          "content": "<p>第一个内容项...</p>",
          "author": "作者"
        },
        {
          "title": "第二条内容",
          "content": "<p>第二个内容项...</p>",
          "digest": "摘要"
        }
      ]
    }
  }'
```

## 🔌 客户端集成

### Claude 桌面应用集成

在 Claude 配置文件中添加：

**Windows:**
```json
{
  "mcpServers": {
    "wechat-post": {
      "command": "node",
      "args": ["C:\\path\\to\\wechat-post-mcp\\dist\\index.js"],
      "env": {
        "WECHAT_APP_ID": "your_app_id",
        "WECHAT_APP_SECRET": "your_app_secret"
      }
    }
  }
}
```

**macOS/Linux:**
```json
{
  "mcpServers": {
    "wechat-post": {
      "command": "node",
      "args": ["/path/to/wechat-post-mcp/dist/index.js"],
      "env": {
        "WECHAT_APP_ID": "your_app_id",
        "WECHAT_APP_SECRET": "your_app_secret"
      }
    }
  }
}
```

### Node.js 客户端示例

```javascript
import { Client } from '@modelcontextprotocol/sdk/client/index.js';
import { StdioClientTransport } from '@modelcontextprotocol/sdk/client/stdio.js';

async function main() {
  const transport = new StdioClientTransport({
    command: 'node',
    args: ['/path/to/wechat-post-mcp/dist/index.js'],
    env: {
      WECHAT_APP_ID: process.env.WECHAT_APP_ID,
      WECHAT_APP_SECRET: process.env.WECHAT_APP_SECRET,
    }
  });

  const client = new Client({
    name: 'example-client',
    version: '1.0.0'
  }, {
    capabilities: {}
  });

  await client.connect(transport);

  // 发布文章
  const result = await client.callTool('post_article', {
    title: '我的文章',
    content: '<p>文章内容</p>',
    author: 'John Doe',
    digest: '这是摘要'
  });

  console.log('发布结果:', result);
  await client.close();
}

main().catch(console.error);
```

### Python 客户端示例

```python
import subprocess
import json

# 启动 MCP 服务器
process = subprocess.Popen(
    ['node', '/path/to/wechat-post-mcp/dist/index.js'],
    env={
        'WECHAT_APP_ID': 'your_app_id',
        'WECHAT_APP_SECRET': 'your_app_secret'
    },
    stdin=subprocess.PIPE,
    stdout=subprocess.PIPE,
    stderr=subprocess.PIPE,
    text=True
)

# 发送 MCP 请求
request = {
    "jsonrpc": "2.0",
    "id": 1,
    "method": "tools/call",
    "params": {
        "name": "post_article",
        "arguments": {
            "title": "My Article",
            "content": "<p>Article content</p>",
            "author": "John Doe"
        }
    }
}

process.stdin.write(json.dumps(request) + "\n")
process.stdin.flush()

# 读取响应
response = process.stdout.readline()
print("Response:", json.loads(response))
```

## 📁 项目结构

```
wechat-post-mcp/
├── src/
│   ├── index.ts              # MCP 服务器主程序
│   ├── wechat-client.ts      # 微信 API 客户端
│   └── test-mcp.ts           # 测试脚本
├── dist/                      # 编译输出（生产使用）
│   ├── index.js
│   ├── wechat-client.js
│   └── *.d.ts                # TypeScript 类型定义
├── node_modules/             # 依赖包
├── package.json
├── tsconfig.json             # TypeScript 配置
├── .env.example              # 环境变量示例
├── .gitignore
└── README.md
```

## 🔐 安全性指南

### ⚠️ 敏感信息管理

- ❌ **不要** 在代码中硬编码 APP_ID 和 APP_SECRET
- ✅ **使用** 环境变量或密钥管理系统
- ✅ **保护** .env 文件（确保在 .gitignore 中）
- ✅ **定期** 轮换微信账号凭证
- ✅ **监控** MCP 服务器日志以检测异常

### 网络安全

- 仅在可信网络上运行 MCP 服务器
- 考虑使用反向代理（如 Nginx）进行额外的访问控制
- 使用 TLS 加密通信（如需网络传输）

### 微信 API 限制

- 了解微信官方 API 的速率限制
- 实现重试机制和错误处理
- 定期检查 token 有效期

## 🐛 故障排除

### 获取 Token 失败

**症状：** `Error getting WeChat token`

**解决步骤：**
1. ✅ 验证 WECHAT_APP_ID 和 WECHAT_APP_SECRET 正确
2. ✅ 检查网络连接是否正常
3. ✅ 确认微信 API 服务是否可访问
4. ✅ 检查账号是否处于正常状态

### 发布失败

**症状：** `Error publishing article`

**常见原因及解决：**

| 问题 | 解决方案 |
|------|--------|
| 内容不符合规范 | 检查文章内容是否符合微信政策 |
| 媒体 ID 无效 | 确保使用 post_article 返回的有效 mediaId |
| 账户权限不足 | 检查公众号是否拥有发布权限 |
| Token 过期 | 重启 MCP 服务器以刷新 token |

### 模块加载失败

```bash
# 错误：Missing required environment variables
# 解决：确保环境变量已设置
export WECHAT_APP_ID=xxx
export WECHAT_APP_SECRET=xxx

# 或使用 .env 文件
cp .env.example .env
# 编辑 .env 填入凭证
```

## 📊 开发信息

### 编译项目

```bash
npm run build
```

### 开发模式（自动编译）

```bash
npm run dev
```

### 环境变量

| 变量 | 说明 | 示例 |
|------|------|------|
| `WECHAT_APP_ID` | 微信应用 ID | `wx1234567890abcdef` |
| `WECHAT_APP_SECRET` | 微信应用密钥 | `abc123def456...` |

## 📚 技术文档

- [MCP 官方文档](https://modelcontextprotocol.io/)
- [微信官方 API 文档](https://developers.weixin.qq.com/)
- [Node.js MCP SDK 文档](https://github.com/modelcontextprotocol/sdk)

## 🤝 贡献

欢迎贡献代码！请遵循以下流程：

1. Fork 项目
2. 创建功能分支 (`git checkout -b feature/AmazingFeature`)
3. 提交更改 (`git commit -m 'Add some AmazingFeature'`)
4. 推送到分支 (`git push origin feature/AmazingFeature`)
5. 打开 Pull Request

## 📝 许可证

本项目采用 ISC 许可证。详见 [LICENSE](LICENSE) 文件。

## 📞 支持

- 📖 查看 [README.md](README.md) 获取完整文档
- 🐛 在 [GitHub Issues](https://github.com/your-username/wechat-post-mcp/issues) 报告 Bug
- 💬 提出功能请求和讨论

## 🎉 致谢

- [Model Context Protocol](https://modelcontextprotocol.io/) - MCP 标准
- [微信官方 API](https://developers.weixin.qq.com/) - 微信服务支持
- 所有贡献者

---

**最后更新：** 2024-08-10  
**维护者：** GitHub Copilot