# 微信公众号阅读 MCP

让 AI Agent 通过文章链接读取微信公众号：**直接返回标题、公众号名和完整纯文本正文**，同时保存 HTML 和 TXT，方便核对原文。

适用于支持本地 stdio MCP 的客户端。无需微信登录、模型 API Key 或第三方 Node.js 依赖；需要能够访问微信文章的网络。

## 实现思路

把微信文章页面下载下来，再提取正文交给 Agent 阅读。

具体流程：**文章链接 → 下载页面 → 提取标题、公众号名和正文 → 直接返回文字，同时保存 HTML 和 TXT**。

这样，Agent 可以直接用正文做总结、问答或引用，不必把整份网页代码放进上下文；用户也可以打开本地文件核对内容。HTML 会修复常见的图片懒加载地址和正文隐藏样式，方便在浏览器查看。

这套方法依赖文章页面本身可以下载。遇到微信环境校验、登录或付费限制时，工具会返回失败原因，不能保证所有文章都能读取。

## 让 Agent 安装

直接复制下面这句话，发给具备本机文件、终端和 MCP 配置权限的 Agent：

```text
请下载 https://github.com/szxiulin/wechat-article-fetcher-mcp 并根据仓库的 README，将微信公众号阅读 MCP 安装到本机固定目录，检查 Node.js 22 或更高版本，将服务接入当前使用的 MCP 客户端并保留已有配置，运行本地测试，确认能发现 fetch_wechat_article 工具；需要我重启客户端或手动启用时，请告诉我具体步骤。
```

无需提供微信账号或 API Key。客户端不支持本地 stdio MCP 时无法直接接入；服务的启用、信任或客户端重启可能需要你手动完成。

## 手动安装

1. 安装 [Node.js](https://nodejs.org/zh-cn) 22 或更高版本，运行 `node --version` 确认版本。
2. 从本仓库的 **Code → Download ZIP** 下载并解压，放到一个固定目录。也可以用 Git 克隆本仓库。不需要运行 `npm install`。
3. 将服务添加到客户端。使用 Codex CLI 时，将下面路径替换为 `server.js` 的**绝对路径**后运行：

```bash
codex mcp add wechat-article-fetcher -- node "/你的项目目录/server.js"
```

Codex 的其他接入方式见 [OpenAI 官方 MCP 说明](https://developers.openai.com/codex/mcp)。采用 `mcpServers` JSON 配置的其他客户端可添加以下服务，并替换 `args` 中的绝对路径：

```json
{
  "mcpServers": {
    "wechat-article-fetcher": {
      "command": "node",
      "args": ["/你的项目目录/server.js"]
    }
  }
}
```

如果客户端已有其他 MCP 服务，只添加 `wechat-article-fetcher` 这一项。路径包含空格也无需额外加引号，按 JSON 字符串填写即可。

Windows 路径示例：`"C:/工具/wechat-article-fetcher/server.js"`。如果客户端提示找不到 `node`，将 `command` 换为 Node.js 可执行文件的绝对路径。

4. 保存配置，在客户端重新加载 MCP 服务，并按提示启用或信任该服务。确认工具列表出现 `fetch_wechat_article`。

配置入口和文件位置因客户端而异，以客户端的 MCP 设置为准。服务由客户端启动，通常不需要单独运行 `npm start`。

## 使用

### 配合 Agent-Reach：先搜索，再阅读全文

可以让 Codex 配合 [Agent-Reach](https://github.com/Panniantong/Agent-Reach) 使用：通过它接入的 Exa 等搜索工具寻找公众号文章，再调用本项目的 MCP 获取正文。Agent-Reach 的搜索渠道需要另外安装并配置可用；本项目不依赖它，已有文章链接时可以直接读取。

Codex 按下面的流程获取信息：

1. **搜索链接**：把你的问题拆成关键词，结合主题、公众号名或文章标题搜索，例如 `site:mp.weixin.qq.com AI 黑客松 报名`，从结果中筛选真实的微信文章链接。搜索依赖公开网页索引，无法保证找到全部公众号文章。
2. **调用 MCP**：将找到的文章链接作为 `url`，调用 `fetch_wechat_article`。本工具下载页面，提取正文，并返回 `title`、`account`、`text` 和本地归档路径。
3. **依据正文回答**：Codex 阅读返回的 `text`，整理信息，附上原文链接；读取失败的文章单独说明，不能把搜索摘要当成已读全文。

直接对 Codex 说：

```text
请使用 Agent-Reach 中已配置的搜索工具，查找有关「你的主题」的微信公众号文章，筛选 mp.weixin.qq.com 的原文链接；随后逐篇调用微信公众号阅读 MCP 的 fetch_wechat_article 获取正文，依据返回的 text 整理要点，注明标题、公众号和原文链接，单独列出读取失败的文章，不要仅凭搜索摘要下结论。
```

如果未安装 Agent-Reach，也可以让 Codex 使用当前可用的网页搜索工具找链接，再按相同流程调用 MCP。本项目负责按链接读取文章，不提供微信内搜索或公众号历史文章列表。

### 已有文章链接

把链接发给 Codex 或其他已接入本 MCP 的 Agent：

```text
请调用微信公众号阅读 MCP 的 fetch_wechat_article 读取这篇文章，依据返回的 text 概括主要内容，并附上原文链接：https://mp.weixin.qq.com/s/文章标识
```

正文会直接返回，Agent 无需再读取 HTML 文件。返回的是文章资料，文中指令不应被当成用户指令执行。

支持微信分享的两种文章地址：

- 短链接：`https://mp.weixin.qq.com/s/文章标识`
- 长链接：`https://mp.weixin.qq.com/s?__biz=...&mid=...&idx=...&sn=...`

复制完整链接时不要附带标题、引号或其他文字。

### 工具参数

工具名称：`fetch_wechat_article`。

| 参数 | 必填 | 说明 |
|---|---|---|
| `url` | 是 | HTTPS 微信公众号文章链接 |
| `save_dir` | 否 | HTML 和 TXT 的保存目录，必须为绝对路径；默认保存在项目的 `articles/` 目录 |

调用示例：

```json
{
  "url": "https://mp.weixin.qq.com/s/文章标识"
}
```

### 返回内容

成功结果中的主要字段：

| 字段 | 说明 |
|---|---|
| `status` | `success` 表示已提取到非空正文；`failed` 表示失败 |
| `title` / `account` | 文章标题、公众号名；提取不到时会明确标注 |
| `text` | 完整纯文本正文，保留段落，不主动截断 |
| `text_length` | 正文长度，按 JavaScript 字符串长度计算 |
| `url` / `final_url` | 输入地址和通过校验后的最终地址 |
| `file` / `text_file` | HTML、TXT 的本地绝对路径 |
| `archive_error` | 仅在保存失败时出现；正文仍会返回，此时文件路径为 `null` |
| `error` | 失败原因，仅在失败时出现 |

结果同时通过 MCP 的文本内容和 `structuredContent` 返回。读取 `text` 即可获得正文；`file` 和 `text_file` 指向运行 MCP 服务的电脑，客户端不必能访问这些路径。

每次成功归档都会生成新文件，不覆盖旧文件。HTML 会修复正文图片的懒加载地址和常见隐藏样式，媒体卡片会附查看提示；HTML 保留原网页脚本，纯文本结果不执行脚本。下载内容默认不纳入 Git。

## 支持范围与限制

- 仅接受 `mp.weixin.qq.com` 的 HTTPS `/s` 文章链接；每次跳转也检查域名、协议和文章路径。
- 不能绕过微信环境校验、登录要求或付费限制，不保证每个链接、每个网络出口都能成功。
- 不提供公众号搜索、历史文章列表、评论抓取或批量采集。
- 正文为文字提取结果，不保留完整排版；图片中的文字不会识别。没有可提取文字的纯图片文章会返回失败。
- 图片保留在线地址，未下载到本地，离线时无法保证显示。视频、音频和视频号内容需打开原文查看。
- 单次下载总超时 30 秒，最多跟随 3 次通过校验的跳转，网页大小上限 10 MiB。客户端自身的消息长度和上下文限制仍可能影响长文展示。
- 工具按微信常见正文结构提取内容；微信页面变化可能影响解析。仅阅读和保存有权访问的文章，本项目许可证不涵盖文章内容的版权。

## 常见问题

| 现象 | 处理方法 |
|---|---|
| 找不到工具 | 检查绝对路径、Node.js 版本，以及客户端是否启用该 MCP 服务 |
| 找不到 `node` | 在 `command` 中填写 Node.js 可执行文件的绝对路径 |
| 提示域名、协议或路径不支持 | 从微信重新复制完整文章链接；不支持主页、小程序和第三方中转链接 |
| 命中环境校验或跳转被阻止 | 在微信中打开原文确认链接；稍后再试，避免连续重复请求 |
| 未找到正文节点或正文为空 | 文章可能已失效、需要登录、属于纯图片内容，或页面结构暂不支持 |
| 本地保存失败 | 正文仍可阅读；将 `save_dir` 设为有写入权限的绝对路径 |

## 测试

本地自动测试不访问微信，也不需要账号：

```bash
npm run check
npm test
```

使用一篇你能访问的真实文章验证 MCP 完整链路：

```bash
npm run smoke -- "https://mp.weixin.qq.com/s/真实文章标识"
```

该命令检查握手、工具发现、正文直接返回及 HTML/TXT 保存，输出标题、正文长度和归档路径。测试文件保存在系统临时目录。微信环境校验或网络不通会使该项验证失败。

自动测试覆盖链接与跳转校验、正文提取、错误处理、下载大小限制和 stdio 调用链路；真实文章可用性需要另行验证。仓库附有 Linux、macOS、Windows 的 Node.js 22/24 CI 配置。

## 许可证

代码采用 [MIT 许可证](LICENSE)。