上周我接到一个需求把三百多个Excel文件里散落的销售记录合并成一张总表顺便清洗重复项和乱码。换作以前我的做法很固定——打开Python写脚本挨个文件遍历、拼接、清洗花上小半天。但这次我换了一条路先给AI装上一副操作Excel的手也就是标题里说的MCPModel Context Protocol再让AI自己拆解任务、调用工具、完成全流程。从零写一个MCP Server到接入AI客户端前后只花了不到一天。这篇就把我开发第一个MCP的完整过程、代码、配置和踩坑经验都摊开来说适合所有会用一点Python、又想让AI帮忙处理重复Excel工作的读者。1. 为什么我决定用MCP重构Excel处理流程1.1 常规方式的三个痛点先说传统做法。普通人拿到合并三百个Excel并清洗数据这种需求大概会面临三个选择第一手工打开Excel复制粘贴人肉跑数据容易漏、容易错时间还不可控第二让AI直接读文件但现在的AI对话窗口有上下文限制你把一个Excel的内容粘进去都费劲更别说批量处理十几个文件第三找程序员写脚本需求沟通一轮、改参数一轮、交付再迭代一轮等脚本能用数据需求早就变了。我自己以前也是第二种加第三种混着来。python批量处理Excel本身不复杂用pandas循环读取、concat、再清洗几十行代码能搞定。但问题在于这是一次性活每次换一批文件、换一种统计口径都得回头改脚本非常烦人。而且同事没法学领导想看一眼进度你也只能把运行截图贴过去。1.2 MCP补上了什么短板MCP解决的核心问题就是让AI从只能聊天变成能动手操作具体软件。它很像给AI装了一双手AI通过标准协议去调用你写好的工具函数这些函数去读Excel、算汇总、写回结果AI再根据工具返回的数据继续推理和下结论。打个比方以前让AI处理Excel相当于你口述需求让一个看不见文件的助手凭想象给你提建议有了MCP之后AI可以直接打开文件看内容像人手一样操作单元格最后把整理好的结果递给你。协议本身解决的是AI客户端和本地脚本之间怎么通信、怎么描述工具、怎么传参数这几个标准问题相当于给助手配了一副能看见文件的手套。下面我拿一个具体的月底销售报表场景来对比两种路径你就能直观感受差别。对比维度传统prompt 脚本MCP方案数据获取需要手动把数据粘贴进对话或提前写好文件上传AI直接通过工具读取本地文件无上下文压力批量处理每次换文件要改脚本路径和参数工具固定AI每次只传不同参数即可非程序员使用学不会改脚本在客户端里发一句话就能执行中间过程透明脚本过程黑盒报错才看到AI会说明调用了哪些工具、得到什么结果扩展性每开一个新需求就要新写一套脚本在同一个MCP Server上挂新工具即可对我这种长期跟Excel打交道的人来说MCP把代码能力和AI理解力做了个乘法AI负责理解需求和拆解步骤代码负责确定性地执行操作。这个组合一旦跑通Excel相关的工作流就再也不是写死脚本那种玩法了。提示MCP是软件协议不是某个特定软件。它定义的是一套AI客户端如何发现并调用外部工具的通用规则所以同一个MCP Server可以在Claude Desktop、Cline、Cherry Studio等不同客户端里复用。2. 开发前先想清楚边界、粒度、权限很多新手一上来就急着写代码结果写出来的Server要么是一堆重复工具要么把危险操作暴露给AI要么工具参数设计得让AI根本不知道怎么传。我自己第一版就吃过这个亏。所以动键盘之前我建议你先花半小时回答三个问题。2.1 职责边界这个Server到底管哪些事第一个问题是Server的服务范围。你的MCP是只服务Excel数据清洗还是连生成图表发邮件操作文件夹都一起管我的建议是第一个MCP一定收窄边界只做一类事。我当时把边界定成四个动作读表读Excel结构、查数查询单元格区域、统计按条件筛选汇总、写回把AI处理过的数据保存为新的Excel。定了边界之后工具列表、参数设计、返回值格式都变得很清晰。你要是把删文件这种Powershell操作也塞进来AI调用起来爽但事故风险也大。还要给文件路径做约束。MCP Server运行在你的机器上AI客户端只要拿到工具就能调用理论上可以读你任意一个路径。我建议在Server里做一个可访问根目录的概念所有读写操作都限制在一个项目目录下比如D:\data\excel_workspace。这样即使AI在测试中乱传路径也只会碰到该目录不会摸到系统文件。注意MCP工具的权限就是你的代码权限。你写了shutil.rmtreeAI就真的能删目录你用了pathlib.Path.unlinkAI就能删文件。所以工具内部必须做参数校验和路径白名单别图省事直接透传。2.2 工具粒度一个工具最好只干一件事第二个问题是工具怎么拆。很多非科班出身的朋友容易写一个全能工具——输入文件路径、表名、条件、统计字段、输出路径然后一个函数里又是读又是算又是写。表面看一次调用搞定但实际使用时AI常常传错或漏传参数而且不好复用。正确做法是按读数据-算数据-写数据分层每个工具只负责一个最小环节。比如读取Sheet结构是一个工具按条件筛选并求和是一个工具追加写入新Sheet又是一个工具。这样AI面对复杂任务时会自动拆解成多步逐步调用每一步的输入输出都很清晰。我还给每个函数写了详细的docstring让AI能通过函数说明了解这个工具的用途、参数含义、返回格式。FastMCP会把docstring一起暴露给客户端相当于给AI一份工具说明书。2.3 权限红线默认只读写操作要单独声明第三个问题是权限。别看这是个本地小工具权限设计直接影响安全性。我给每个工具分了三类只读型read开头、计算型不落盘、写型write开头。写型工具一律要求传入明确的输出文件名并且我限制它只能写到配置好的输出目录内。AI写完文件后我的Server会返回已保存到xxx路径共N行让AI知道发生了什么方便它继续汇报。还有一个容易被忽略的点控制并发和长任务。有些AI客户端会并行调用多个工具如果你的Server一次性处理几个大文件内存容易爆。我在工具里做了简单的并发控制——用一个全局锁让同一个时间只处理一个文件避免pandas反复读取大Excel时把内存吃满。这在单体小工具阶段不是最优解但胜在稳。这些问题想清楚之后代码写起来就顺畅多了。下面是我实际实现的Server代码你直接抄过去改改路径就能跑。3. 我的第一个Excel MCP Server逐行实现3.1 技术选型为什么是FastMCP pandas openpyxlMCP Server可以用官方SDK写也可以用社区封装好的FastMCP库。我选FastMCP核心原因是它把大量协议细节封装掉了。你只需要写普通Python函数加一个mcp.tool()装饰器FastMCP会自动帮你生成工具的JSON Schema、处理参数校验、管理stdio通信开发和调试体验好很多。至于Excel处理pandas负责读取和统计openpyxl作为pandas的引擎补齐Excel格式细节。安装很简单在你的项目虚拟环境里执行pip install fastmcp[pandas] pandas openpyxlpandas的Excel读写依赖openpyxlFastMCP的pandas扩展会帮你把pandas DataFrame转成Markdown表格文本返回给AI这个后面细说。3.2 搭建Server骨架和文件白名单先写一个骨架重点是路径白名单和工具注册。from fastmcp import FastMCP from pathlib import Path import pandas as pd BASE_DIR Path(D:/data/excel_workspace) # 允许访问的根目录 OUT_DIR BASE_DIR / outputs OUT_DIR.mkdir(exist_okTrue) mcp FastMCP(excel-helper) def safe_path(user_path: str, for_write: bool False) - Path: 把用户传入的相对/绝对路径二次校验到BASE_DIR内。 p Path(user_path) if not p.is_absolute(): p BASE_DIR / p p p.resolve() base BASE_DIR.resolve() if not (p base or base in p.parents): raise PermissionError(f路径超出允许范围: {p}) if for_write: p OUT_DIR / p.name # 写操作强制落到outputs目录避免覆盖源文件 return psafe_path是整个Server的安全基石。resolve()会把路径里的..和软链接解析掉防止AI传一个D:/data/excel_workspace/../../Windows/system32之类的路径绕过验证。写操作我做了更狠的限制不管用户传什么文件名最终都落到固定输出目录下从根上堵住覆盖源文件的风险。3.3 实现四个Excel工具第一个工具获取Excel文件的所有Sheet名称和大致结构。mcp.tool() def list_sheets(file_path: str) - str: 列出Excel文件中所有工作表的名称和每个Sheet的行列数。 Args: file_path: Excel文件路径相对于BASE_DIR或含BASE_DIR的完整路径。 p safe_path(file_path) if not p.exists(): return f错误文件不存在 {p} try: xl pd.ExcelFile(p) lines [f文件: {p.name}] for name in xl.sheet_names: df xl.parse(name, nrows1) nrows, ncols df.shape lines.append(f- Sheet[{name}]: {nrows} 行预览 / {ncols} 列) return \n.join(lines) except Exception as e: return f读取失败: {e}Excel文件一般有多个SheetAI在处理数据前必须先知道有哪些Sheet、每个Sheet大致什么规模否则后面很容易指定错表名。这个工具返回的信息会作为AI规划下一步的依据。第二个工具读取指定Sheet的数据支持数量和列筛选。mcp.tool() def read_sheet(file_path: str, sheet_name: str, max_rows: int 100) - str: 读取Excel指定Sheet的前N行数据返回Markdown表格。 Args: file_path: Excel文件路径。 sheet_name: 工作表名称大小写敏感。 max_rows: 最多读取行数防止一次读入大量数据占满上下文默认100。 p safe_path(file_path) if not p.exists(): return f错误文件不存在 {p} try: df pd.read_excel(p, sheet_namesheet_name, nrowsmax_rows) return df.head(max_rows).to_markdown(indexFalse) except Exception as e: return f读取失败: {e}这里用了to_markdown把DataFrame转成AI更容易理解的Markdown表格。你可以看到工具返回值不是给人看的而是给AI看的所以格式必须结构化。早期我试过直接str(df)结果中文内容混在一起AI经常误解换成Markdown表格后准确率明显提升。第三个工具按条件筛选并求和这是销售报表场景中最常用的动作。mcp.tool() def filter_sum(file_path: str, sheet_name: str, column: str, keyword: str, sum_column: str) - str: 筛选某列包含指定关键词的行对另一列求和。 Args: file_path: Excel文件路径。 sheet_name: 工作表名称。 column: 用于筛选的列名。 keyword: 要匹配的关键词支持子串匹配。 sum_column: 需要求和的数值列名。 p safe_path(file_path) if not p.exists(): return f错误文件不存在 {p} try: df pd.read_excel(p, sheet_namesheet_name) if column not in df.columns: return f错误列[{column}]不存在现有列: {list(df.columns)} if sum_column not in df.columns: return f错误列[{sum_column}]不存在 filtered df[df[column].astype(str).str.contains(keyword, naFalse)] total pd.to_numeric(filtered[sum_column], errorscoerce).sum() count len(filtered) return f筛选[{column}]含{keyword}命中{count}行{sum_column}合计: {total} except Exception as e: return f统计失败: {e}注意filter_sum里面没有返回整张筛选表而是返回一个摘要结论。这是MCP工具设计里很重要的一条AI每次返回的内容都会进入对话上下文如果你让它把筛选后的几千行全部返回上下文直接就爆了。摘要式返回让AI既拿到关键结论又不至于淹没在海量数据里。如果AI后续需要明细它可以再调用read_sheet按需读取。第四个工具把AI处理好的数据写回Excel这是重构工作流的最后一环。mcp.tool() def write_dataframe(file_path: str, sheet_name: str, data: str) - str: 把JSON格式的二维数组写入Excel文件的新Sheet。 Args: file_path: 输出文件名不包含路径自动保存到outputs目录。 sheet_name: 目标Sheet名已存在则覆盖。 data: JSON字符串格式为二维数组例如 [[\日期\, \销售额\], [\2025-01-01\, 100]]。 import json, io p safe_path(file_path, for_writeTrue) rows json.loads(data) if not isinstance(rows, list) or not rows: return 错误data必须是二维JSON数组 df pd.DataFrame(rows[1:], columnsrows[0]) try: with pd.ExcelWriter(p, engineopenpyxl, modew) as writer: df.to_excel(writer, sheet_namesheet_name, indexFalse) return f已写入 {p}Sheet[{sheet_name}]共{len(df)}行 except Exception as e: return f写入失败: {e}这个工具的输入是一段JSON二维数组维度是AI需要生成一张新表格时用的。比如AI读完原始数据、做了一轮筛选和汇总后需要给出一张结果表它就可以把结果组织成[[日期,金额],[2025-01-01,123]]传给write_dataframe。这里我特意把列表推导成DataFrame再写Excel的逻辑简单化是因为AI生成复杂嵌套结构容易出错二维数组是它能稳定生成的最简单结构。3.4 启动Server并自测FastMCP的启动非常轻量在文件末尾加上if __name__ __main__: mcp.run()然后命令行执行python excel_server.py如果没有任何报错Server就在stdio模式下等待客户端连接了。不过这时你去敲命令行是看不到任何输出的因为协议走的是标准输入输出内容全部在和AI客户端交互。想单独调试工具逻辑我建议你先在Server里临时加一段自测代码用字典逐个调用函数验证结果通不过就改通过再正式挂到客户端上。能把ABAC路径清理、读结构、读数据、筛选统计、写回到Excel五个环节串起来这个Server就已经具备处理实际Excel工作流的能力了。接下来要解决的是怎么把它接到AI客户端里让AI真正用起来。4. 接入AI客户端并跑通一条真实任务链路4.1 客户端配置给AI一把打开工具箱的钥匙MCP Server是后台服务AI客户端是前台操作界面。目前主流的AI客户端基本都支持MCPClaude Desktop、ClineVS Code插件、Cherry Studio等。我以Claude Desktop为例配置方式是在配置文件里声明服务器名称、启动命令和参数。{ mcpServers: { excel-helper: { command: python, args: [D:/projects/excel_mcp/excel_server.py], env: { PYTHONUNBUFFERED: 1 } } } }配置里的command和args指定了怎么启动这个Serverenv.PYTHONUNBUFFERED1是为了避免Python的输出缓冲导致和客户端通信卡顿这个不加在一些环境里会踩坑。保存配置后重启客户端正常情况下客户端会多出一个工具列表里面能看到list_sheets、read_sheet、filter_sum、write_dataframe这四个工具。注意不同客户端配置文件的位置不一样Claude Desktop是claude_desktop_config.jsonCline是在VS Code扩展配置里填MCP Servers。但配置结构基本一致都是mcpServers对象下挂服务器名称、command、args这几项。4.2 设计一条可验证的任务客户端没有现成文档教你怎么测所以我给自己设计了一条能明确验证对错的任务避免AI自个儿发挥半天最后结果对不上。我准备的测试环境是D:/data/excel_workspace下一个叫sales.xlsx的文件里面有Sheet1和Sheet2两个工作表。Sheet1是原始销售记录包含列日期、区域、产品、销售员、金额、数量、状态。Sheet2是类似结构的另一批数据。我的核心任务是合并两个Sheet的数据筛选状态为已完成的记录按区域汇总金额把汇总结果写回一个新Excel文件。这条任务逻辑复杂但是结果可判定合并、筛选、分组、求和、落盘每个环节都能人工核对。如果AI能自主完成说明工具链跑通了如果中途报错我也有明确的排查边界。4.3 观察AI的调用过程和思维链我把任务丢给客户端然后盯着工具调用日志这是我第一次如此直观地看到AI自己思考并动手的过程。AI大致做了这么几步第一步它调用list_sheets(sales.xlsx)确认文件里有哪些Sheet。返回给我的是Sheet1, 100行预览 / 6列这样一行信息。这里的100行预览是我用nrows1做的预览实际上list_sheets并不读全表所以AI只知道大概行数。第二步它调用read_sheet(sales.xlsx, Sheet1, max_rows100)快速获取表头结构和数据样例。AI看到列名之后会复用同样的方式读Sheet2。第三步它意识到需要合并。Human爱拿试试看的心态操作AI也会自己尝试。它直接调用filter_sum分别对Sheet1和Sheet2做了状态含已完成的筛选求和验证两个Sheet的数据能不能对上。第四步发现不能直接合并——两个Sheet的列名不完全一致Sheet2有几行列名是英文的。于是AI在对话里对我说Sheet2的列名不一致我准备先读取全量数据并在工具外部用pandas逻辑处理但没有合并工具时我需要你提供处理后的数据。 这一步特别典型它是中文理解是我遇到了工具的边界但策略很合理它没有假装能处理而是把问题暴露给我。第五步我追加了一个步骤教它使用write_dataframe工具。AI会先构造一个二维数组把两个Sheet数据按统一列名对齐筛选status为completed的数据按区域求和最后把结果通过write_dataframe写回。结果文件里出现了正确的汇总表。整个过程大概花了三分钟期间AI一共调用了十几次工具。对我这种习惯脚本一次跑通的人而言它更像是一个远程实习生在有条不紊地干活每步都有汇报错了会说明比写死脚本灵活得多。经验MCP不是让AI自动写好脚本的工具而是让AI直接拥有操作数据的工具习惯。AI看到工具清单后会自己规划行动路径这比它凭空生成pandas代码再让你执行要稳定得多——因为它能根据实际返回的数据随时微调策略。4.4 跑通之后怎么验证结果调用链路跑通不等于结果正确。我的验证方法是把源数据手工算一遍再和AI写回的结果文件比对。拿按区域汇总已完成订单金额来说我在Excel里直接用数据透视表算了一遍得到华东68.4万元、华北52.1万元、华南47.6万元。AI的输出文件和我的结果一致才说明整条工作流的逻辑是通的。这种情况如果万一对不上我一般按下面顺序排查先看AI有没有读错Sheet名或列名工具返回里能看到再看筛选条件已完成到底匹配的是状态列还是别的列有没有把空值也筛进去再看数字类型Excel里有些金额列存的是文本求和时会变成0这就要在Server里加pd.to_numeric处理最后看是不是列名对齐问题多表合并时最常见。这一轮跑下来我对AI 工具的组合有了新认识它的价值不在于一次写对而在于错了能及时发现、能自己调整策略、能透明汇报每一步。这是传统脚本完全不具备的。5. 调试中踩过的坑从工具返回没人能读懂到AI乱用旧数据第一次开发MCP踩坑几乎是必然的。我把最磨人的四个问题记录下来每个都附上了定位思路和修复方案希望你能少走弯路。5.1 坑一工具返回值格式不对AI直接理解失败现象是AI执行完工具后在对话里说工具返回了错误或无法解析的数据但实际上Server端明明正常执行了。定位过程我先在Server端加了日志发现函数返回值是一个多行字符串其中包含中文括号、引号和数字。我怀疑是Markdown格式问题但更关键的是——我返回的内容里既有表格又有说明文字混在一起之后AI对到底哪部分是数据、哪部分是说明产生了歧义。修复方案我把所有工具返回值统一成两种格式要么是完整的Markdown表格要么是一段可解析的JSON绝不两者混用。read_sheet返回完整的表格filter_sum返回结构化文本例如命中8行金额合计: 65000.00write_dataframe返回明确的状态描述。这样AI每次拿到返回值都能稳定解析。教训MCP工具返回文本不是给人看的它最终会被AI当成输入继续推理。所以返回值要结构优先宁可多几个换行也不要把表格和散文揉在一坨。5.2 坑二参数Schema和AI预判不一致现象AI调用read_sheet时经常把sheet_name传成sheet1小写但Excel里的Sheet名其实是Sheet1或者把max_rows传成字符串100。定位过程我在Server函数的docstring里详细写了sheet_name的说明但AI仍然是按自己的理解去生成参数。FastMCP会从类型注解自动生成Schema所以参数类型是没问题的真正的问题是很多Excel用户在命名Sheet时并不严格AI无法预知是大小写敏感还是忽略大小写。修复方案我在read_sheet里加了大小写不敏感的模糊匹配——先精确匹配匹配不到就遍历sheet_names做lower()比较。同时在docstring里补充说明Sheet名大小写不敏感可以传任意大小写。参数类型问题则在函数内部用int()做一次强制转换防止个别客户端把数字当字符串传进来。5.3 坑三同一个目录下有多个MCP Server工具名冲突现象是客户端工具列表里出现两个read_sheet分别来自不同ServerAI调用时报工具返回错误但日志显示函数根本没被调起来。定位过程我原本在自己的标准Server里挂了一个read_sheet某个周末又顺手起了另一个测试Server也定义了read_sheet两个Server同时挂到同一个客户端。AI在选择工具时随机挑了一个但那个Server可能有不同的实现路径于是行为不可预期。修复方案把工具名加上业务前缀比如excel_read_sheet、excel_filter_sum。同时养成习惯每加一个新Server之前检查一遍已挂载的工具名。这样就算多个Server共存AI也能通过名字判断该用哪个。5.4 坑四AI在连续调用时乱用旧数据现象AI第一次调用filter_sum得到华东合计68万第二次换成华北时返回结果还是68万但它自己完全没有察觉继续拿错的数据推理。定位过程我调出工具调用日志发现第二次调用确实传入了正确的华北参数Server也返回了51万但AI对话里引用的仍是第一次的68万。这说明数据本身没错问题出在AI客户端的上下文管理——它可能把工具输出和对话历史混在一起生成了错误的引用。修复方案这个坑不是工具端能唯一解决的。我在Server端返回时把筛选条件明文写进结果里例如筛选[区域]含华北金额合计: 510000。这样即使AI引用时拿错数字下一轮它也会从返回文本里看到带华北字样的结果降低混淆概率。另外在给AI布置任务时我会特别提示它每一步工具返回结果后先确认返回结果里的筛选条件是否和你要的一致再写入你的结论。实测下来误用率明显下降。调试的经验总结下来其实就一句话永远假设AI会乱来、会误解、会拿旧数据然后在整个链路上给AI足够多的显式上下文标记。工具返回什么、筛选条件是什么、数据时间是什么都写在返回文本里让它每一次决策都有参照物。6. 从第一个MCP延伸出去我总结出的复用模式第一个MCP跑通后我又在同一个Server上挂了几个工具顺便把日常重复的Excel活全部迁了过来。这里有一些很值得说的体会。6.1 同一个Server挂更多工具从Excel到文件组织Excel处理是最容易起效的场景但不是唯一场景。我在excel-helper这个Server上陆续加了两个工具merge_excels把目录下多个同类Excel合并成一个DataFrame并写回、generate_report接受AI生成的Markdown报告文本自动转成Excel并套一个简单样式。这两个工具和之前的四个配合一套日常报表工作流基本就成型了。另外我另起了一个文件管理Server工具只做三件事列出目录文件、读取文本文件、按文件名模式移动文件。这让AI能帮我整理下载目录、归档项目资料。每一个Server的边界都控制得很窄但组合起来覆盖了我工作中百分之七八十的重复文件操作。建议你也这样第一个MCP不要追求大而全先把一类操作做扎实跑顺之后再去扩展第二个Server。一个能用的窄工具比十个躺在列表里没人调的宽工具强得多。6.2 给新手的三个实操建议第一工具返回永远给摘要。能返回5000行数据不等于要返回5000行AI上下文是稀缺资源每个工具都应该返回够AI做决策即可的信息量。读取时用max_rows限制统计时给汇总值明细需要时再单独读。第二每个工具都要写清晰的docstring。FastMCP会把docstring转换成给AI看的函数描述写得越清楚AI调用正确率越高。用词上尽量描述工具会做什么、返回什么、典型使用场景而不是写此函数执行某些操作这种废话。第三先做自测再做集成。我最初几版工具函数全是直接在客户端里测的报错了很难区分是工具逻辑问题还是AI误调用问题。后来改成先本地单测确认函数返回格式稳定了再挂客户端。这一步省下的调试时间至少一半。6.3 为什么不建议一上来就用别人做好的现成MCP市面上已经有一些Excel相关的MCP Server可以直接下载使用。但我的建议是第一个MCP仍然值得自己写一遍。原因是别人做的Server永远是从他自己的业务出发设计的工具参数、返回格式、权限策略不一定和你的工作流匹配。而你一旦自己写过一遍就掌握了MCP的完整工作方式——知道工具怎么被AI发现、怎么传参、怎么返回。等到你去用那些成熟方案时你能一眼看出它和你业务不匹配的地方也能更快改造成自己的东西。这个项目的意义对我不只是一串能跑的代码它让我重新理解了AI落地的一个最佳姿势AI负责拆解目标、安排行动代码负责确定性地执行原子操作。两者之间用MCP这个标准协议握手AI豁然开朗代码也终于有了一个会自己思考的调用者。如果你手上也积压着大量Excel填报、汇总、清洗的活不妨从今天开始给自己写第一个MCP半天时间换一条重构后的工作流这笔账怎么算都不亏。