Windows 配置 chatExcel-MCP完整踩坑指南

实战踩坑记录

从零开始，在 Windows + Claude Code 环境下成功配置 chatExcel-MCP，遇到了 6 个真实问题并一一解决。

Windows 11

Claude Code

Python 3.12

6 个坑全踩过

目录

1. 背景：为什么要配置这个
2. 坑 1：pip 命令找不到
3. 坑 2：Python 3.14 太新，包不兼容
4. 坑 3：requirements.txt 编码错误
5. 坑 4：依赖版本冲突
6. 坑 5：MCP 连接失败（print 污染 stdout）
7. 最终成功：31 个工具全部加载

00

背景

chatExcel-MCP是一个基于 MCP 协议的 Excel 智能处理服务器，提供 31 个工具，支持 Excel 读写、数据分析、图表生成、公式解析等功能。配合 Claude Code 使用后，可以用自然语言直接操作 Excel 文件。

本文记录了在 Windows 环境下从克隆项目到成功连接的全过程，以及遇到的每一个问题和解决方法。

01

坑 1：pip 命令找不到

报错

pip : 无法将"pip"项识别为 cmdlet、函数、脚本文件或可运行程序的名称。

原因分析

Python 安装路径下，python.exe加入了系统 PATH，但pip.exe所在的Scripts\目录没有加入。两者目录不同。

解决方案

用python -m pip代替pip，让 Python 直接调用内置的 pip 模块，绕过路径问题。

# ❌ 报错 pip install -r requirements.txt # ✅ 正确 python -m pip install -r requirements.txt powershell

02

坑 2：Python 3.14 太新，包不兼容

报错

ERROR: Could not find a version that satisfies the requirement pandas==2.2.3 (from versions: 2.3.3, 3.0.0...)

原因分析

Python 3.14 是最新版本，很多库（pandas、scipy 等）还没有发布对应的预编译包（wheel）。pip 找不到兼容版本，只能从源码编译，而源码编译又需要 Fortran 编译器，Windows 上默认没有。

解决方案

安装 Python 3.12，这是目前兼容性最好的版本。Windows 支持多版本共存，用py -3.12指定版本即可，不用卸载 3.14。

# 下载 Python 3.12 安装时务必勾选： ☑ Add Python to PATH # 验证安装 py -3.12 --version # Python 3.12.7 # 后续所有命令用 py -3.12 前缀 py -3.12 -m pip install -r requirements.txt powershell

03

坑 3：requirements.txt 编码错误

报错

UnicodeDecodeError: 'gbk' codec can't decode byte 0xae in position 39

原因分析

requirements.txt 文件包含中文注释，保存为 UTF-8 编码。但 Windows 的 pip 默认用 GBK/CP936 读取文件，遇到 UTF-8 特有字节就报错。

解决方案

用 PowerShell 强制以 UTF-8 读取再重新保存，生成新文件后安装。

# 转换编码，生成新文件 Get-Content requirements.txt -Encoding UTF8 | Set-Content requirements_utf8.txt -Encoding UTF8 # 用新文件安装 py -3.12 -m pip install -r requirements_utf8.txt powershell

04

坑 4：依赖版本冲突

报错

ERROR: Cannot install pydantic-settings==2.7.0 and pydantic-settings==2.9.1 because these package versions have conflicting dependencies.

原因分析

这个项目的 requirements.txt 写得很乱，同一个包pydantic-settings在文件不同位置出现了两次，而且版本号不同。这是项目本身的问题，不是环境问题。

解决方案

跳过这个混乱的 requirements.txt，只手动安装真正需要的核心包。原则：只装运行时必须的包，去掉测试工具、监控工具、可选功能等开发专用包。

# 直接安装核心依赖，跳过冲突 py -3.12 -m pip install fastmcp mcp pandas openpyxl xlsxwriter numpy matplotlib seaborn plotly chardet scipy tabulate formulas pydantic-settings python-dotenv loguru psutil rich requests httpx uvicorn pydantic pyyaml powershell

05

坑 5：MCP 连接失败（最难的一个）

报错

chatExcel: ... ✗ Failed to connect（直接运行 server.py 完全正常，但 claude mcp list 就是连不上）

原因分析

MCP 协议通过stdout（标准输出）传递 JSON 消息。server.py 里所有的print()语句（比如"✓ 成功导入模块"这些提示）也输出到了 stdout，把 JSON 消息"污染"了。Claude Code 收到一堆夹杂着 emoji 的文本，无法解析 MCP 协议，所以连接失败。

解决方案

在 server.py 顶部添加几行代码，将所有print()输出重定向到 stderr，保持 stdout 干净只传 JSON。

# 用 PowerShell 在文件顶部插入重定向代码 $content = Get-Content "...\server.py" -Encoding UTF8 -Raw $insert = "import sys`nimport builtins`n_orig_print = builtins.print`nbuiltins.print = lambda *a, **k: _orig_print(*a, file=sys.stderr, **k)`n`n" $new = $insert + $content Set-Content "...\server.py" -Value $new -Encoding UTF8 powershell

核心原理

MCP 是基于 stdio 的协议：stdout 是"信道"，只能传 JSON；stderr 是"日志"，可以随便写。所有调试输出必须走 stderr。

06

最终成功：31 个工具全部加载 🎉

# 验证连接 claude mcp list chatExcel: ... ✓ Connected # 启动 Claude Code claude powershell

启动后，Claude Code 已经可以识别全部 31 个 chatExcel 工具，直接用自然语言操作 Excel：

# 示例用法 > 帮我分析 C:\Users\xxx\Desktop\销售数据.xlsx，找出每月业绩趋势 > 把这个 Excel 的数据生成一个交互式折线图 > 清洗数据，删除空白行并按日期排序 claude code

6 个坑，6 个经验

有问题欢迎评论区交流，特别是 MCP stdout 污染这个坑，很多人都会踩到。