最近很多朋友问我MCP到底是个什么东西网上教程一堆但看完还是不知道从哪下手。我的建议从来都是别去背概念直接做一个自己天天用得上的小工具。我选的场景就是Excel——每天都要处理表格报表、数据清洗、把杂乱的无格式数据整理成规范格式……这些重复劳动浪费了太多时间。这篇文章记录我开发自己的第一个MCP服务器的完整过程用Python写一个MCP服务让AI能直接读取、分析、写入Excel文件把“和表格打交道”这件事交给AI去干。我会把从零到一的思路、代码、配置、踩的坑全部写出来。适合想入门MCP开发、平时又离不开Excel的读者有一点Python基础就能跟上。1. 为什么第一个项目选“Excel MCP”1.1 被Excel重复劳动逼出来的真实念头我一开始也没想过要给AI做工具真正促使我动手的是日常工作的“痛苦感”。你想象一下这样的日子早上收三个同事发来的表格式五花八门中午老板要“把上周的数据按地区汇总”下午又要从几百行明细里筛出某个渠道的记录。每一件都不难但每一件都要人工打开文件、人工翻找、人工复制粘贴。一天下来表格处理消耗的时间远超真正做判断的时间。有人会说这不就是写脚本能解决的吗确实能可问题在于写脚本之前我要先把需求理解透再翻译成pandas代码跑完之后还要把结果翻译回同事能看懂的人话。换句话说工具一直存在但“人肉翻译”这一层从来没省掉。传统工作流里人始终是那个把自然语言转成代码、再把代码结果转回自然语言的中间件。1.2 MCP给AI补上了“能动手”的接口MCP的全称是Model Context Protocol直译过来是“模型上下文协议”。它在2024年底被开放成标准协议本质是给AI模型和外部工具之间定一套统一的“插拔接口”。我不喜欢背定义打一个比方你就懂了MCP出现之前AI调用工具是“闭门造车”式的各家搞各家的接口A家的插件接到B家的模型上大概率不干活MCP出现之后整个关系变成了你手机上的USB-C接口——镜头、读卡器、麦克风只要是Type-C口插上就能用。MCP就是AI世界的Type-C。我们平时用网页版AI聊天AI之所以干不了实事是因为它被锁在对话框里。你说“把这份Excel清洗一下”它看不到文件、碰不到磁盘只能给你写一段你自己去跑的代码。而一旦有了MCPAI就能通过协议直接调用你注册好的工具读文件、写文件、筛选数据全在对话里完成。自己开发一个MCP说白了就是给AI“造一个趁手的工具”让它能在你的电脑上真正开始干活。1.3 选取Excel作为突破口的四个理由先说结论Excel是个人开发者练手MCP最理想的第一站不是因为它潮恰恰因为它普通。第一场景足够高频。任何上班族都离不开表格开发完的成果每天都能用上正反馈来得快。第二反馈足够直观。AI调用完工具之后结果对不对打开Excel看一眼就知道不需要复杂的验收环境。第三技术栈成熟。Python读写Excel有pandas和openpyxl两大工具库不需要你从零造轮子可以把全部精力放在学习MCP机制本身。第四可扩展性强。你把这个流程打通之后后面想做PDF处理、本地文件管理、API数据聚合全是同一套方法论只是工具的“躯体”不同而已。1.4 MCP工作流和传统工作流的差别我实际用下来的感受可以用“跑腿环节移交给AI”来总结。传统流程中人要做信息抽取、格式转换、重复筛选这些脏活累活MCP工作流把这些臭烘烘的环节全部包给了模型和工具链人只需要说清楚目标、检查最终结果。环节传统工作流MCP工作流理解需求人脑理解自然语言模型直接理解自然语言读取文件手动打开Excel肉眼扫描AI调用read_excel工具筛选/清洗手工排序、筛选、删除AI调用filter_rows等工具生成结果手动另存为、复制粘贴AI调用write_excel复核人工逐步对账人工只看最终结果和关键中间态注意重构不等于彻底取代人。我的判断是判断力、异常识别、最终确认依然留给人类被替换掉的只是重复的机械操作。基于这个定位开发目标就很清晰了我们需要的不是一个大而全的“办公机器人”而是一个能在数据世界里帮我们跑腿的“数字助理”。2. 开发前必须想清楚的方案选型2.1 MCP的三层结构Host、Server、Protocol理解MCP抓住三个角色就够了。Host也叫客户端或宿主就是运行大模型和界面的应用比如Claude Desktop、Cline这类工具。它负责和用户对话也负责帮用户调用外部工具。Server就是你自己写的服务端程序里面注册了一个个“工具”。每个工具本质上就是一个能完成具体任务的函数比如“读取Excel”“写入Excel”“筛选数据”。Protocol则是夹在Host和Server之间的通信规范定义了工具怎么被发现、怎么被调用、结果怎么返回。整个调用链条是这样用户在客户端提问模型发现当前任务需要某个工具于是客户端把调用请求发给服务器服务器执行完把结果返回给客户端模型再基于结果组织语言回答用户。对你这个项目来说核心工作就一件写一个Server把Excel能力注册成工具。2.2 传输方式本地开发优先用stdioMCP协议目前有三种主要的传输方式。stdio通过标准输入输出通信零网络开销、配置简单适合本地场景也是新手入门的首选。你只要在客户端配置文件里指定“运行哪条命令启动服务器”剩下的交给协议本身。SSE通过HTTP端口通信适合服务器部署在另一台机器、或者希望多个客户端共享一个服务实例的场景代价是要暴露端口、要考虑鉴权和并发。新出的Streamable HTTP可以认为是SSE的进阶形态但想法没有变。第一个项目强烈建议用stdio把链路先跑通。不要一上来就追求“远程生产力形态”你的目标是用最小的成本看到AI真的能把Excel处理掉而不是先纠结网络拓扑。2.3 开发框架官方SDK的FastMCP风格MCP开发有两条路。一条是偏底层的直接用官方mcp库实现工具发现、初始化握手、消息循环优点是透彻掌握协议细节缺点是样板代码多。一个最简单的“hello world”工具光初始化就要写五六十行新手很容易被劝退。另一条是官方SDK内置的FastMCP风格封装可以把它理解成Flask之于Web开发装饰器一标函数一写工具就注册好了初始化、握手、消息循环这些细节由框架处理。我这篇文章的代码就是用这种写法。它最大的价值是让你把注意力集中在“业务逻辑”上不被协议细节分散。依赖安装方面我用的是下面几项pip install mcp pandas openpyxl tabulate建议Python版本不低于3.10。太老的版本在类型注解和文件路径处理上会踩不少坑。2.4 第一版功能清单只做能用的闭环我见过太多初学者一上来就想做一个“全功能Excel MCP”计划表里写了十几个工具最后没有一个能完整跑通。这个项目我坚持最小可用闭环先把链路走通再做增强。第一版就规划了四个工具工具名功能说明对应痛点read_excel读取指定工作表的数据行每次都要人工打开文件看内容get_sheet_info查看工作表结构和行列概况不知道文件里到底装了什么write_excel将AI整理好的数据写入Excel复制粘贴容易错位、丢格式filter_rows按关键词筛选数据行手工CtrlF一条条排查够用就行。这四个工具覆盖了“读、查、筛、写”四个最典型环节AI组合调用它们就能完成很多实际任务。3. 从零搭建第一个MCP服务器完整代码与接入3.1 工程结构与依赖安装我的工程目录非常简单没有用复杂的包结构excel-mcp/ server.py workspaces/workspaces是放业务Excel文件的工作目录为什么单独建一个目录我后面会在“安全边界”一节详细解释。先把习惯养成所有被AI操作的文件都放在这个白名单目录里。安装依赖的顺序也有讲究。建议先升级pip再装这几样pip install -U pip pip install mcp pandas openpyxl tabulatetabulate可能容易被忽略但pandas的to_markdown方法依赖它。没有这个库程序运行到表格格式化那一步会直接报错。3.2 server.py完整实现与代码解读下面是我测试通过的完整代码。全程用中文注释写清楚这对工具非常重要——因为模型的“工具说明书”就是函数的签名和docstring注释越清晰AI调用越准确。from pathlib import Path import io import pandas as pd from mcp.server.fastmcp import FastMCP # 白名单目录只允许工具操作这个目录下的文件 WORKSPACE Path(__file__).parent / workspaces # 初始化MCP服务器名称会显示在客户端 mcp FastMCP(excel-assistant) def _resolve_path(file_path: str) - Path: 把输入的文件路径解析为白名单内的绝对路径防止路径穿越。 p Path(file_path) if not p.is_absolute(): p WORKSPACE / p p p.resolve() # 校验路径必须位于工作区内 if not p.is_relative_to(WORKSPACE.resolve()): raise ValueError(f无权访问该路径: {file_path}) return p mcp.tool() def read_excel(file_path: str, sheet_name: str , max_rows: int 100) - str: 读取Excel文件中的表格数据。 参数: file_path: 文件名或相对路径相对于工作区目录 sheet_name: 工作表名留空则读取第一个工作表 max_rows: 最多返回多少行默认100最大1000 返回: Markdown格式的表格内容 path _resolve_path(file_path) if not path.exists(): return f错误文件不存在 {path.name} df pd.read_excel(path, sheet_namesheet_name if sheet_name else 0, nrowsmin(max_rows, 1000)) if df.empty: return 没有读取到数据。 return df.to_markdown(indexFalse, numalignleft) mcp.tool() def get_sheet_info(file_path: str) - str: 查看Excel文件有哪些工作表以及每个表的行列概况用于快速了解文件结构。 path _resolve_path(file_path) if not path.exists(): return f错误文件不存在 {path.name} xl pd.ExcelFile(path) lines [f文件: {path.name}, f工作表数量: {len(xl.sheet_names)}] for name in xl.sheet_names: df xl.parse(name, nrows5) lines.append(f- {name}: 采样{len(df)}行 x {len(df.columns)}列列名: {list(df.columns)}) return \n.join(lines) mcp.tool() def write_excel(file_path: str, data: str, sheet_name: str Sheet1) - str: 将CSV格式的文本数据写入Excel文件首行作为表头。 参数: file_path: 目标文件名 data: CSV文本内容例如 姓名,部门\\n张三,技术部\\n李四,运营部 sheet_name: 工作表名默认Sheet1 返回: 写入结果说明 path _resolve_path(file_path) df pd.read_csv(io.StringIO(data), encodingutf-8) if df.empty: return 错误没有可写入的数据。 with pd.ExcelWriter(path, engineopenpyxl, modew) as writer: df.to_excel(writer, sheet_namesheet_name, indexFalse) return f写入成功{path.name}共{len(df)}行 mcp.tool() def filter_rows(file_path: str, keyword: str, column: str ) - str: 在Excel表格中搜索包含指定关键词的行。 参数: file_path: 文件名 keyword: 要搜索的关键词 column: 指定在哪个列搜索留空则在所有列中搜索 返回: 匹配到的数据行Markdown格式 path _resolve_path(file_path) if not path.exists(): return f错误文件不存在 {path.name} df pd.read_excel(path) if column: mask df[column].astype(str).str.contains(keyword, naFalse) else: mask df.apply( lambda row: row.astype(str).str.contains(keyword, naFalse).any(), axis1 ) result df[mask] if result.empty: return f在{len(df)}行数据中没有找到包含「{keyword}」的记录。 return result.to_markdown(indexFalse, numalignleft) if __name__ __main__: mcp.run()代码不到100行但覆盖了工具注册、路径安全校验、数据读写逻辑。核心要理解三点。第一mcp.tool()装饰器就是注册工具的关键。函数的docstring会被AI当作“工具说明书”读取所以每个参数都要写清楚是什么、默认值是什么。模型会根据这些描述决定怎么调用、传什么参数。第二_resolve_path这套白名单校验务必保留。很多教程示例把路径校验省掉了实际上这是把“让AI操作你电脑文件”的安全底线丢掉了。后面我还会专门展开讲。第三工具命名要直白。read_excel就是读表filter_rows就是筛行。别起花里胡哨的名字模型理解起来又快又准。3.3 本地验证用MCP Inspector试跑工具写好代码之后强烈建议不要直接接客户端先用MCP Inspector验证一遍。在项目目录下执行python -m mcp dev server.py命令会启动一个本地调试服务你可以从终端给的地址打开浏览器界面看到服务器提供了哪些工具选择某个工具、填入参数、直接调用立刻看到返回结果。如果没有安装命令行工具也可以用npx方式npx modelcontextprotocol/inspector python server.py我的习惯是先用Inspector把四个工具逐个调一遍确认read能出表、write能建文件、filter能筛对人再去做客户端接入。这一步能把“服务器本身的问题”和“客户端连接的问题”分隔开排查会轻松很多。3.4 接入Claude Desktop的配置步骤工具本身跑通之后剩下的就是把服务器“挂”到客户端上。以Claude Desktop为例在它的配置文件claude_desktop_config.json里加入下面的内容{ mcpServers: { excel-assistant: { command: python, args: [D:/projects/excel-mcp/server.py] } } }注意command和args要写对。Windows上python命令有时候不在PATH里这时候要把解释器的完整路径写进去比如C:/Users/你的用户名/AppData/Local/Programs/Python/Python311/python.exe。路径分隔符建议用正斜杠/因为JSON里反斜杠是转义符直接用Windows的反斜杠很容易把配置搞坏。配置完成后重启客户端通常能在对话界面看到“已连接工具”一类的提示说明AI已经具备了调用Excel工具的能力。这时候你可以直接说“读取workspaces目录下的销售明细.xlsx帮我筛选出金额大于10000的行。”如果一切正常模型会自动决定先调用get_sheet_info了解文件结构再调用read_excel或filter_rows执行任务全程不需要手动点开Excel。4. Excel工具开发中的关键细节与安全边界4.1 大文件读取别让一次调用吃掉全部内存很多人的Excel看起来只有几百KB加上公式和样式之后变成几百MB也很常见。你的MCP工具如果每次都全量读入内存模型还没开始分析机器先卡住了。我在read_excel里给max_rows设了默认100、上限1000就是故意“限制”AI的手脚。它在初步了解时只需要看前几行确认工作表结构后再按需扩大读取范围。这个“分步读取”的思路让大文件场景的体验好了很多。另外pandas读取Excel时会对列做类型推断。混着数字和文本的列经常被猜错比如“00123”被读成数字123。如果发现AI读出来之后数据对不上可以提示AI在调用工具时明确指定读取方式或者在Excel里提前把这类列的格式改成文本。这个问题不是MCP特有的是pandas处理的固有特性但在AI调用场景里会被放大因为你可能不会像以前那样逐个单元格检查。4.2 写入策略新建文件与修改旧表要分开write_excel默认用的modew也就是目标文件已存在时直接覆盖整个工作簿。测试场景下没问题但真实办公里同事发来的表可能带着一堆格式、图表、透视表一个覆盖操作全部灰飞烟灭。更稳妥的做法是分两种场景。如果是AI生成的新数据要写新文件直接modew新建没问题。如果要修改已有表格老老实实走openpyxl读进来再改指定单元格不要用pandas整体覆盖。openpyxl可以按单元格写入并保留其他所有内容from openpyxl import load_workbook def update_cell(file_path: str, sheet_name: str, row: int, col: int, value) - str: wb load_workbook(file_path) ws wb[sheet_name] ws.cell(rowrow, columncol, valuevalue) wb.save(file_path) return 单元格已更新“覆盖原表”这种操作一旦由AI自动执行代价比人手工失误大得多。开发时宁可在工具设计阶段多暴露一些选项也不要让AI默认就对正式文件动手。这属于一开始就要想清楚的边界问题。4.3 并发调用给工具说明书加上约束你不妨试一次同时让AI“统计各部门人数并各自写一个result文件”你会在工作目录看到服务器同时收到多次写入调用。FastMCP本身支持并发执行工具但pandas写Excel时对同一个文件的并发写会直接报错。解决思路有两个。一是在工具设计上约定每次写入用时间戳或随机后缀生成文件名避免冲突。二是更简单的做法在write_excel的docstring里加一句“执行写入操作时不要并行一次只写一个文件”模型通常会遵循工具说明书上的约定。临时文件也是个隐藏细节。AI执行中间过程可能会写出中间结果这些文件容易堆积。可以在工作区里建一个temp目录在工具文档中写明“中间文件默认放temp目录”定期清理即可。4.4 安全底线用白名单目录限定AI的活动范围这可能是整个项目里我最想强调的一节。当你把“能操作你电脑文件的AI”装到客户端时你实际上把外部模型的能力延伸到了本地文件系统。模型可能因提示词注入被操纵也可能因理解偏差去改动不该动的文件。我的原则是MCP工具默认只给白名单目录里的文件操作权限。服务器启动时创建workspaces目录所有工具操作的文件路径必须resolve之后仍在这个目录内否则直接拒绝。这样即便AI“乱来”伤害也被限制在一个沙箱里。桌面、系统目录、项目源码文件夹都碰不到。具体到代码层面就是那个_resolve_path函数。别看它只有几行作用非常关键。新手做第一个MCP时务必把安全边界一并做上这比多写一个工具重要得多。有了这层防护你才敢放心地对AI说“帮我把这些表合并了”。5. 常见问题排查实录与速查表5.1 客户端找不到MCP服务器的排查顺序一半以上的配置问题都出在两个原因上。第一个是command路径不对。特别是Windows下python解释器并不都在PATH里客户端按“python”找不到命令。排查方法是在终端执行where python把完整路径填进配置。第二个是启动报错被吞掉。客户端经常只显示一句“连接失败”不显示Python的报错信息。这时候不要盯着配置反复看直接把启动命令在终端手动执行一遍python D:/projects/excel-mcp/server.py把报错修完再回客户端重试。这个思路适用于所有MCP排障先证明服务器能自己跑起来再检查连接配置。5.2 中文乱码与路径坑pandas读CSV遇到中文乱码几乎都是编码问题。Excel的xlsx格式不算有这个问题但如果你让AI顺手处理CSV记得在工具实现里明确编码参数pd.read_csv(path, encodingutf-8-sig)utf-8-sig比utf-8更适合Windows环境因为它会正确跳过BOM头Excel打开也不乱码。中文路径方面Path的resolve方法能正确处理中文真正容易出问题的是客户端配置JSON里的中文和反斜杠。JSON里反斜杠是转义符Windows路径要用正斜杠“/”或者把反斜杠写成双反斜杠“\\”。很多新手在这里折腾半天最后发现就是少写了一个斜杠。5.3 工具超时与任务拆分策略MCP工具默认有执行时间限制。如果你的工具要处理大文件一个跑30秒的任务很容易被客户端判定超时。两种处理思路一是对工具本身加限制超大文件直接拒绝并提示“文件过大请分批处理”二是拆分任务粒度让一次工具调用只做一件小事比如“读取前100行”“筛选某一列等于某值”由模型在对话里多次调用组合来完成大任务。我实测下来“小工具、多调用”的体验远好于“大工具、孤注一掷”。因为模型每一步都能看到中间结果发现异常可以即时调整策略而不是等最后一步崩了才发现前面的数据不对。这也是为什么我把默认max_rows设成100而不是设成一次性全读。5.4 问题速查表为了方便调试我把这个项目踩过的坑整理成一个速查表。现象原因解决方案客户端找不到服务器python命令不在PATH配置里写python完整路径JSON配置加载失败反斜杠被转义路径改用正斜杠“/”启动没有报错但连不上服务器初始化异常被吞终端手动跑server.py看输出中文CSV乱码编码不一致read_csv指定utf-8-sig大文件调用超时单次任务过重拆分任务限制默认nrows写入覆盖原表格式modew整表覆盖旧表修改用openpyxl按单元格写入同一文件并发写报错pandas不支持同一文件并发写docstring要求串行操作AI读不到文件路径不在白名单内文件放workspaces目录6. 下一步把第一个MCP变成日常工具6.1 实测感受这些场景真的变快了项目跑通之后我连续用了一周总结了真正省时间的场景。最典型的是“清洗不规范表格”同事发来一个列名乱七八糟、带合并单元格的明细表以前要手工调整半天现在直接让AI“把列名改成规范格式删除空行把金额转成数字”三步内搞定。其次是“按条件提取数据”几百行的客户名单按地区、按金额区间、按时间范围筛AI调用filter_rows工具几秒出结果。但也有不适合的场景。比如需要精细排版、带特定企业模板的报表AI生成的格式还是需要人工调涉及复杂公式链和透视表联动的表格AI目前也只能“看懂”数据未必能维持公式逻辑。我的判断是不要期待MCP解决所有表格问题把重复、琐碎、判断简单的事情交给它人去做真正需要业务理解的事情。6.2 可扩展的方向与生态参考第一个MCP跑通之后可以扩展的方向其实很多。你可以给服务器增加工具合并多个Excel、按列拆分工作表、批量转换为CSV这些都是高频需求。也可以把服务器从stdio升级到SSE部署到公司内网服务器上让多个同事共享同一个MCP服务。再往外看MCP生态里已经有浏览器自动化、数据库操作、设计软件脚本插件等大量服务器。任何一个场景都可以按“定义工具、实现函数、注册服务”这套模式去套。当你自己开发过一个之后再看那些成熟的MCP服务器不会再觉得神秘因为它们骨子里就是一堆注册好的工具函数。我个人在这几次迭代里最大的体会是做第一个MCP最大的收获不是代码本身而是真正理解了“AI Agent是怎么干活的”。当你看着模型自己决定先读哪个工作表、再调什么参数筛选数据、最后把结果写成新文件那种“工具链在AI手里被自主编排”的感觉比看一百篇文章都直观。最后说个实在的建议别等“彻底学会了再写”。花五分钟搭一个最小服务器注册一个“读Excel”的工具让AI帮你干一件平时重复的小事。从那个时刻起你就不再是看客了。MCP这东西名字唬人拆开就是你给AI写的一个个函数。动手之后你会发现门槛比想象中低得多上限却高得多。