1. 为什么要在 Windows 上折腾 weixin_search_mcp
如果你经常需要查公众号文章，又不想每次手动翻历史记录，weixin_search_mcp 这个 Python 项目值得试一下。它本质上是一个 MCP（Model Context Protocol）服务，把「按关键词搜索公众号文章」这件事封装成标准接口，任何支持 MCP 的客户端都能直接调用。换句话说，你本地跑一个服务，Claude Desktop、Cursor、Cline 这类工具就能像调用内置能力一样去搜公众号内容。
但真正让人头疼的不是装依赖，而是两件事：一是本地服务默认只监听 127.0.0.1，外部客户端根本连不上；二是每个客户端都要单独配一套 Key 和地址，管理起来很乱。我这次的做法是：Windows 本地用 Python 跑 weixin_search_mcp，通过内网映射把端口暴露出去，再用 TaoToken 的统一 Key 和 API 通道把模型调用和 MCP 服务串起来。这样外部客户端只需要认一个地址、一个 Key，链路就通了。
适合谁看：手上有 Windows 机器、装了 Python、想让本地 MCP 服务被外部访问的开发者；或者已经在用 MCP 客户端、想接一个公众号搜索能力进去的人。下面按「装服务 → 配 Key → 映射端口 → 验证」的顺序走一遍，命令和配置都能直接复制。
2. 前置准备：Python 环境与 TaoToken 统一 Key
先把地基打好。Windows 上建议用 Python 3.10 以上，3.11 更稳。装完 Python 后确认 pip 可用，然后准备 git。这两样是拉项目和装依赖的前提。
python --version pip --version git --version如果版本号都能正常打印，说明环境没问题。接下来是 TaoToken 这一层。它的作用是给你一个统一的 API 入口和 Key，模型对话、编码计划、MCP 服务接入都走同一个通道，省得每个服务单独申请凭证。你需要拿到两样东西：API Key 和接入地址。
- 官网入口：https://taotoken.net/?utm_source=taotoken_aicg_blog_end&utm_medium=csdn&utm_campaign=rewrite&utm_content=
- API 地址：https://taotoken.net/api
- 创建 Key 的页面：https://taotoken.net/api-keys?utm_source=taotoken_aicg_blog_end&utm_medium=csdn&utm_campaign=rewrite&utm_content=api-keys
注意：API 地址不要加 UTM 参数，直接写 https://taotoken.net/api 就行，带参数的地址在某些客户端里会被当成非法路径。
拿到 Key 之后先别急着填，后面配置里会用到。这里有个容易踩的坑：Key 要放在环境变量或配置文件里，别硬编码进代码提交到仓库。我一般用.env或者系统环境变量，下面配置示例里会体现。
3. 本地部署 weixin_search_mcp 的完整步骤
3.1 克隆项目与安装依赖
打开 PowerShell 或 CMD，找一个你习惯放项目的目录，执行克隆。项目地址是公开的，直接拉。
git clone https://github.com/wbsu2003/weixin-search-mcp.git cd weixin-search-mcp pip install -r requirements.txt依赖装完后，先别急着跑。建议建一个虚拟环境，避免污染全局包。如果你已经习惯全局装，跳过也行，但虚拟环境更干净。
python -m venv venv venv\Scripts\activate pip install -r requirements.txt激活虚拟环境后命令行前面会出现(venv)标识。这一步在 Windows 上偶尔会遇到执行策略限制，如果报无法加载文件...因为在此系统上禁止运行脚本，用管理员身份打开 PowerShell 执行Set-ExecutionPolicy RemoteSigned即可。
3.2 配置 config.toml 与 settings.json
weixin_search_mcp 的配置分两块：服务本身的参数，以及 MCP 客户端怎么连它。下面给一份可直接复制的骨架。
config.toml放在项目根目录，主要控制监听地址和端口：
[server] host = "0.0.0.0" port = 8000 debug = false [search] max_results = 10 timeout = 30 [taotoken] api_base = "https://taotoken.net/api" api_key = "${TAOTOKEN_API_KEY}"这里host写成0.0.0.0是关键，只写127.0.0.1的话内网映射也救不了你，外部根本连不进来。api_key用环境变量占位，实际值在系统里设。
settings.json是给 MCP 客户端用的，比如 Claude Desktop 的配置目录。骨架如下：
{ "mcpServers": { "weixin_search": { "url": "http://你的公网地址:映射端口/mcp", "headers": { "Authorization": "Bearer ${TAOTOKEN_API_KEY}" } } } }url里的公网地址和端口，等内网映射做完再填。Authorization头带上 TaoToken 的 Key，这样客户端请求会经过统一通道鉴权。
3.3 启动服务并确认本地可访问
配置写完，启动服务：
python main.py看到类似Uvicorn running on http://0.0.0.0:8000的输出就说明起来了。先在本地浏览器访问http://127.0.0.1:8000，能看到 MCP 主界面，搜索框输入关键词能返回文章列表，说明服务本身没问题。
如果启动报端口占用，改config.toml里的port，比如换成 8080，然后同步改后面映射的端口。如果报依赖缺失，回到 3.1 确认pip install是否在正确的虚拟环境里执行。
4. 内网映射：让外部客户端能连进来
本地跑通只是第一步，外部客户端要访问，得把 8000 端口映射到公网。这里用内网映射工具，原理是在本地和内网穿透服务器之间建一条隧道，外部请求打到公网地址后转发到你本机的 8000。
操作流程大致是：安装映射客户端 → 添加映射 → 选原生端口 → 内网端口填 8000 → 创建后拿到公网地址。不同工具界面略有差异，但核心参数就三个：内网地址127.0.0.1、内网端口8000、协议选 HTTP 或 TCP。
创建成功后你会得到一条公网地址，形如http://xxxx.xxx.com:12345。把这个地址填回 3.2 的settings.json，注意路径要带上/mcp，因为 MCP 服务通常挂在子路径下。
提示：映射工具的公网地址可能会变，免费版尤其如此。如果客户端突然连不上，先检查映射地址是否更新了。长期用建议选固定地址的方案，或者把地址写进环境变量方便替换。
映射完成后，在外部网络（比如手机热点）用浏览器访问那个公网地址，能看到 MCP 界面就说明链路通了。这一步是整个流程里最容易卡住的地方，如果访问不了，按下面第 5 节的排查顺序走。
5. 三步验证与常见报错排查
5.1 三步验证动作
第一步，本地验证。浏览器开http://127.0.0.1:8000，搜索一个关键词，比如「Python 教程」，看是否返回文章列表。返回正常说明服务本身 OK。
第二步，映射验证。用外部网络访问公网地址，同样搜索，能返回结果说明映射生效。
第三步，客户端验证。在 MCP 客户端里触发一次搜索调用，看是否走通。如果客户端报鉴权失败，检查Authorization头里的 Key 是否正确；如果报连接超时，检查公网地址和端口是否和映射一致。
5.2 常见报错与处理
报错一：Connection refused。服务没起来，或者host没写0.0.0.0。回到 3.3 确认启动日志，检查config.toml。
报错二：401 Unauthorized。Key 不对或没带上。确认环境变量TAOTOKEN_API_KEY已设置，且客户端请求头格式是Bearer <key>。Key 可以在 https://taotoken.net/api-keys?utm_source=taotoken_aicg_blog_end&utm_medium=csdn&utm_campaign=rewrite&utm_content=api-keys 重新生成一个试试。
报错三：映射地址访问 502。隧道通了但本地服务没响应。检查本地 8000 端口是否还在监听，服务是否被防火墙拦了。Windows 防火墙有时候会拦入站，临时关掉测试一下。
报错四：客户端连上但搜不到结果。大概率是搜索参数或上游接口问题。看服务日志里有没有超时或解析错误，config.toml里的timeout可以适当调大。
报错五：路径 404。MCP 客户端配置的 URL 少了/mcp后缀，或者映射工具把路径重写了。确认settings.json里的 url 完整。
排查顺序建议从内到外：先本地、再映射、最后客户端。每层确认通了再往下走，别一上来就怀疑最外层。
6. 把链路固定下来：统一 Key 与后续接入
链路跑通后，建议把配置固化。TaoToken 的统一 Key 在这里的价值是：模型对话、编码计划、MCP 服务接入共用一个凭证，换客户端时不用重新申请。如果你后面要接更多 MCP 服务，或者想让 Agent 长期跑编码任务，可以考虑 Coding Plan，把调用配额和通道统一管理。
- 模型对话入口：https://taotoken.net/chat?utm_source=taotoken_aicg_blog_end&utm_medium=csdn&utm_campaign=rewrite&utm_content=chat
- Coding Plan：https://taotoken.net/coding-plan?utm_source=taotoken_aicg_blog_end&utm_medium=csdn&utm_campaign=rewrite&utm_content=coding-plan
- 接入文档：https://taotoken.net/doc?utm_source=taotoken_aicg_blog_end&utm_medium=csdn&utm_campaign=rewrite&utm_content=doc
实际用下来，这套组合最省心的地方是配置一次、多处复用。本地服务改端口或换机器时，只需要更新映射地址和 Key，客户端那边不用大动。如果你在 Windows 上遇到虚拟环境激活失败，或者映射工具的公网地址频繁变动，优先把这两件事解决，剩下的就是复制粘贴的活。
