最近在折腾 MCPModel Context Protocol把日常的 Excel 数据处理工作流彻底重写了一遍原本要花半小时对表格、写公式、调格式的活现在丢给 AI 就能直接拿到整理好的结果。这篇文章就聊聊我从零开发第一个 Excel MCP Server 的完整过程包括协议原理、代码实现、客户端接入和一堆实操坑希望能给想入坑 MCP 的同学一点参考。先交代下背景我日常要处理大量销售报表、报销明细和库存表格绝大部分时间耗在数据清洗、透视求和、格式调整上。之前试过用 Python 脚本写死流程但表格一换结构就崩用 Excel 公式硬堆又经常被复杂的条件查询绕晕。MCP 的出现让我看到了另一种解法把 Excel 的操作能力封装成标准接口让 AI 自己决定怎么读、怎么算、怎么写我只负责定义好边界。1. 为什么要用 MCP 重构 Excel 处理流程很多人的第一反应是直接用 Python 写 openpyxl 脚本不就完了吗为什么非要绕一圈用 MCP我在实际对比之后才明白这两者的核心区别在于“流程由谁驱动”。1.1 传统脚本方案的三个痛点先说痛点。最早我做表格处理无非两种路子第一种手动操作 Excel。筛选、排序、写公式、拖拽填充一套下来动作重复且容易出错。尤其是“从 20 列数据里挑出满足 5 个条件的行并求和”这种需求眼睛真的会看花。第二种写 Python 脚本。用 openpyxl 或 pandas 处理数据的确快但问题是每次需求一变脚本就得改。今天要按城市汇总明天要按产品线汇总后天又要加一个环比计算。改脚本本身不算麻烦麻烦的是改完还要重新跑、重新调试、重新核对结果这个时间成本一点都不低。而且脚本有个天然缺陷你必须在动手前想清楚所有逻辑。但实际工作里的需求往往是模糊的——“帮我看看这个表有什么问题”“这几个月的销售趋势怎么样”——这种开放性问题脚本根本无从下手。1.2 MCP 带来的本质变化MCP 的思路完全不同。它不把“处理表格”写成一条固定的流水线而是把“读文件”“写文件”“筛选数据”“计算求和”“生成图表”这些能力拆成一个个原子化的“工具”。AI 模型作为大脑根据你的自然语言描述动态决定调用哪些工具、按什么顺序调用。我举个具体的例子。之前让我处理一份“各区域门店 Q3 销售明细”需求是剔除退货记录按区域汇总并且标出环比下降超过 20% 的门店。传统脚本我至少要写几十行代码还要先摸清表格的列名和数据类型。用 MCP 的方式我只需要告诉 AI 这几点它自己会先调用“读取表格结构”的工具再调用“筛选数据”的工具最后把结果写回新表格。整个过程的本质是把“怎么做”交给了 AI我只负责说清“要什么”。这就是我理解的 MCP 核心价值——它不是一个新的数据处理库而是一套让 AI 能安全、可控地操作现实工具的标准协议。提示MCP 本身只是个协议规范真正干活的是你注册进去的那些“工具”。所以开发 MCP Server核心工作就是设计好你的工具函数。2. MCP 核心概念与工具选型开始写代码之前我觉得很有必要先把 MCP 的底层概念理清楚。网上很多教程上来就贴代码看得人一头雾水就是缺少这一层的铺垫。2.1 先搞懂 MCP 的三个角色MCP 的架构看着唬人实际上就是一个标准的“客户端-服务端”模型只不过多了一个 AI 模型在中间当调度员。拆开看就三个角色MCP Host运行 AI 模型的地方比如 Claude Desktop、Cursor、自己写的 Python 程序。它负责理解你的自然语言决定调用什么工具。MCP Server你把能力暴露出来的服务。它维护着一堆“工具”的注册信息并处理实际的执行逻辑。我这次要写的 Excel 处理服务就是这一层。MCP ClientHost 和 Server 之间的连接器。它负责协议握手、调用请求转发、结果返回。实际上 Host 内部通常已经内置了 Client 的角色但在代码里它会作为独立类出现。它们之间的通信方式也值得说一句。MCP 支持两种传输模式stdio和HTTP/SSE。stdio 模式适合本地开发Host 启动一个子进程跑 Server通过标准输入输出进行 JSON-RPC 通信HTTP 模式适合远程部署比如你有一台专门的服务器提供数据处理服务。我这次做的是本地个人工作流所以用 stdio 就够了配置简单且没有网络延迟。协议的底层是 JSON-RPC 2.0每次调用无非是initialize握手、tools/list拿工具清单、tools/call执行具体工具。关于协议细节正常用现成 SDK 开发时基本感知不到但理解这个流程对排查问题很有帮助后面踩坑部分会再提。2.2 自研还是用现成 Server确定要动手之后我面临一个选择自己写一个 Excel MCP Server还是直接用社区里现成的方案现成的方案确实不少。比如有些项目把pandas的常用操作封装成了 MCP 工具注册进去就能让 AI 执行数据筛选、透视、统计。装上就能用适合只想快速体验的人。但我最终选择了自研原因有三第一通用方案不贴我的业务场景。我的表格里有一套固定的“门店编码 区域 品类 销售额 退货率”结构通用工具能处理基础操作但不理解“环比下降超过 20%的门店需要标记”这种业务逻辑。自己封装就可以直接把业务规则写进工具描述里。第二我能更好控制安全边界。MCP 给了 AI 操作真实文件系统的能力这本身就是双刃剑。自己写 Server我可以限制它能访问的目录、能修改的文件后缀、每次写入前是否需要确认。用别人封装好的这些策略往往不可控。第三学习价值完全不同。自己从零实现一遍才能真正理解协议是怎么握手的、工具描述怎么写 AI 才容易理解、超时和错误处理怎么做才健壮。这些东西是直接用现成 Server 永远学不到的。当然如果你只是临时用一用没必要重复造轮子。我的建议是先跑通一个最小的自研 Server哪怕只有一个“读取表格”的工具再回来决定要不要用现成的。跑通一遍的收益远大于直接装个现成的。3. 从零写一个 Excel MCP Server下面进入正题。我会带你完整实现一个能用的 Excel MCP Server功能包括读取表格结构、读取指定单元格区域、写入数据、计算汇总、保存为新文件。运行环境用 Python 3.10核心依赖是mcp官方 SDK和openpyxl。3.1 环境准备与项目结构先初始化项目。我用的是uv管理 Python 环境这套工具现在干净又省心没有的话用venv也一样# 创建项目目录 mkdir excel-mcp-server cd excel-mcp-server # 初始化 Python 虚拟环境 uv venv source .venv/bin/activate # 安装依赖 uv pip install mcp openpyxl # 这俩库就够了 # mcpMCP 官方 Python SDK提供 FastMCP 类 # openpyxl读写 .xlsx 文件项目结构我最终这么组织excel-mcp-server/ ├── server.py # MCP Server 主入口 ├── excel_utils.py # Excel 底层操作函数 ├── config.json # 允许访问的目录白名单等配置 └── requirements.txt我把 Excel 操作单独抽到excel_utils.py而不是全写在server.py里。这样有两个好处一是server.py里的工具函数只做参数校验和描述编写逻辑清晰二是底层操作函数可以独立写单元测试不用启动 MCP 服务就能验证。3.2 用 FastMCP 定义核心工具官方 SDK 提供了FastMCP类极大简化了 Server 开发。你只需要注册几个函数SDK 会自动处理协议握手、工具列表序列化、调用分发。看代码# server.py import json from pathlib import Path from mcp.server.fastmcp import FastMCP # 创建 MCP Server 实例 # 这里的 name 会显示在客户端的工具列表里起个容易识别的名字 mcp FastMCP(excel-assistant) # 从配置文件读取允许操作的目录白名单 ALLOWED_DIRS [Path(d).resolve() for d in json.loads( Path(config.json).read_text(encodingutf-8) )[allowed_dirs]] def _safe_path(file_path: str) - Path: 校验路径是否在白名单内防止 AI 随意读写任意文件 p Path(file_path).resolve() if not any(p.is_relative_to(allowed_dir) for allowed_dir in ALLOWED_DIRS): raise ValueError(f路径 {file_path} 不在允许目录内) return p mcp.tool() def read_excel_structure(file_path: str, sheet_name: str None) - str: 读取 Excel 文件结构返回工作表和表头信息。 Args: file_path: Excel 文件的绝对路径或相对路径 sheet_name: 可选指定工作表名缺省时返回所有工作表名称 p _safe_path(file_path) from excel_utils import get_structure return json.dumps(get_structure(p, sheet_name), ensure_asciiFalse, indent2)这里最关键的是函数名和 docstring 本身就是工具描述的一部分。AI 模型就是根据这段描述来决定“什么时候该调用这个工具”的。所以描述一定要写清楚这个工具是干嘛的、参数分别代表什么、什么时候不要用。我实际测试下来把 docstring 写得越具体AI 的调用准确率越高。比如read_excel_structure如果你只写“读取 Excel”AI 有时候会在只想看一个单元格数据的时候也调它浪费一次工具调用把描述补充成“读取表格文件的工作表列表和字段结构通常用于了解文件概貌适合在数据分析和处理的第一步”之后误调用的频率明显下降。然后注册第二个工具写入数据mcp.tool() def write_excel_data(file_path: str, data: list, sheet_name: str Sheet1, start_cell: str A1, overwrite: bool False) - str: 向 Excel 指定工作表写入数据。 Args: file_path: 目标 Excel 文件路径 data: 二维数组代表要写入的行列数据 sheet_name: 工作表名不存在时自动创建 start_cell: 起始单元格如 A1 overwrite: 是否覆盖已有工作表内容False 时从第一个空行开始追加 p _safe_path(file_path) from excel_utils import write_data rows write_data(p, data, sheet_name, start_cell, overwrite) return f已写入 {rows} 行数据到 {sheet_name}起始单元格 {start_cell}注意到我设计了一个overwrite参数默认是False。这个设计是故意为之AI 在自动化场景下很容易做出“覆盖原始数据”的危险操作默认追加可以大幅度降低误操作风险。宁可数据多几行冗余也别把源头数据改没了。3.3 Excel 底层操作函数实现excel_utils.py里才是真正操作 Excel 文件的地方。我用的是openpyxl它专注于.xlsx格式是当前兼容性最好的选择。# excel_utils.py from pathlib import Path from openpyxl import load_workbook, Workbook from openpyxl.utils import get_column_letter def get_structure(file_path: Path, sheet_name: str None): 获取工作簿结构工作表名列表 每个工作表的行列数和表头 wb load_workbook(file_path, read_onlyTrue, data_onlyTrue) info {file: file_path.name} sheets [] names [sheet_name] if sheet_name else wb.sheetnames for name in names: if name not in wb.sheetnames: raise ValueError(f工作表 {name} 不存在可选{wb.sheetnames}) ws wb[name] rows, cols max(1, ws.max_row), max(1, ws.max_column) headers [cell.value for cell in next(ws.iter_rows(min_row1, max_row1))] sheets.append({name: name, rows: rows, cols: cols, headers: headers}) wb.close() return {sheets: sheets}这里我踩过一个小坑load_workbook如果不加read_onlyTrue大文件加载会非常慢内存占用直接拉满。read_onlyTrue模式只读取必要的单元格数据对“探查结构”这种操作尤其合适。但要注意只读模式下有些 API 不可用比如写数据所以写操作要重新加载。另外data_onlyTrue也很关键。它让公式单元格返回计算后的值而不是公式字符串SUM(A1:A10)。如果你不设这个参数读出来的可能是一堆公式表达式AI 拿到这些数据根本没法做数值分析。def write_data(file_path: Path, data: list, sheet_name: str, start_cell: str A1, overwrite: bool False) - int: 写入二维数据到指定工作表返回写入行数 # 文件存在则加载不存在则新建 if file_path.exists(): wb load_workbook(file_path) else: wb Workbook() # 处理目标工作表新建、复用或清空 if sheet_name not in wb.sheetnames: ws wb.create_sheet(titlesheet_name) else: ws wb[sheet_name] if overwrite: ws.delete_rows(1, ws.max_row) # 解析起始单元格比如 A1 拆成列号1、行号1 col_letter .join(ch for ch in start_cell if ch.isalpha()).upper() start_row int(.join(ch for ch in start_cell if ch.isdigit())) start_col 1 if col_letter: for ch in col_letter: start_col start_col * 26 (ord(ch) - ord(A) 1) for row_idx, row_data in enumerate(data, startstart_row): for col_idx, value in enumerate(row_data, startstart_col): ws.cell(rowrow_idx, columncol_idx, valuevalue) wb.save(file_path) wb.close() return len(data)这里值得注意的一个细节是即使文件不存在也会自动新建这个逻辑在处理“把结果写到新表格”的场景时非常实用。AI 经常说要“新建一个汇总表”与其让它先创建空文件再写数据不如在 Server 端直接把这一步融合进去。3.4 注册汇总分析与公式计算工具第二个核心工具是数据汇总。这个工具解决的是传统脚本最烦的问题——“这个表里每个区域的销售总额是多少退货率最高的门店是哪个”。与其让 AI 调用多次读取再自己计算不如把统计分析做成一个专用工具mcp.tool() def summarize_data(file_path: str, sheet_name: str, group_by: str, value_col: str, agg_func: str sum) - str: 按指定列分组对值列执行聚合操作。 Args: file_path: Excel 文件路径 sheet_name: 目标工作表名 group_by: 分组依据列的表头名称如 区域 value_col: 需要聚合的值列表头名称如 销售额 agg_func: 聚合方式支持 sum/avg/min/max/count默认 sum 使用场景按区域统计销售额、按门店计算平均客单价、按品类统计库存数量等。 p _safe_path(file_path) from excel_utils import aggregate result aggregate(p, sheet_name, group_by, value_col, agg_func) return json.dumps(result, ensure_asciiFalse, indent2)底层实现def aggregate(file_path: Path, sheet_name: str, group_by: str, value_col: str, agg_func: str sum): wb load_workbook(file_path, read_onlyTrue, data_onlyTrue) ws wb[sheet_name] # 获取表头行 headers [cell.value for cell in next(ws.iter_rows(min_row1, max_row1))] if group_by not in headers: raise ValueError(f分组列 {group_by} 不存在可用列: {headers}) if value_col not in headers: raise ValueError(f值列 {value_col} 不存在可用列: {headers}) gi, vi headers.index(group_by), headers.index(value_col) result {} # 从第2行开始遍历数据 for row in ws.iter_rows(min_row2, values_onlyTrue): gkey, val row[gi], row[vi] if gkey is None: continue try: val float(val) except (TypeError, ValueError): continue # 非数值跳过 if gkey not in result: result[gkey] {count: 0, sum: 0.0, min: None, max: None} item result[gkey] item[count] 1 item[sum] val item[min] val if item[min] is None else min(item[min], val) item[max] val if item[max] is None else max(item[max], val) wb.close() # 根据聚合方式返回对应结果 output {} for k, v in result.items(): if agg_func sum: output[k] round(v[sum], 2) elif agg_func avg: output[k] round(v[sum] / v[count], 2) elif agg_func min: output[k] v[min] elif agg_func max: output[k] v[max] else: # count output[k] v[count] return {group_by: group_by, value_col: value_col, agg_func: agg_func, results: output}你可能注意到我在每个工具函数里都写了“使用场景”包括把“什么时候不该用”也写进去。这其实是在看了 AI 多次误调用工具之后总结出的经验工具描述里的每个词都在影响着 AI 的判断。描述越像“说明书”AI 的行为就越可控。尤其在处理模糊请求时一段清晰的工具说明能大大降低 AI 调用错误工具的几率。3.5 启动与测试 Server工具注册完之后启动就一行代码if __name__ __main__: mcp.run(transportstdio)mcp.run()会启动标准输入输出监听。在本地开发时我会配合mcp dev server.py这个命令启动它会自动打开一个调试页面可以在里面模拟 AI 对话直接测试工具调用非常方便。第一次跑通后我用mcp dev做了个快速测试对着一份测试表格说“看看这个表里有哪些工作表”模型立刻调用了read_excel_structure返回了结构信息。那一刻的成就感确实不小第一次真正体会到“AI 在操作我定义的工具”是什么感觉。4. 接入 AI 客户端并落地工作流Server 写好了也测通了下一步就是把它接进真正的 AI 客户端。我最常用的配置环境是 Claude Desktop 和 Cursor这里重点说 Claude Desktop 的配置方法以及一个完整的工作流实测过程。4.1 配置客户端连接 MCP ServerClaude Desktop 的 MCP 配置在配置文件里。不同系统的位置不一样macOS:~/Library/Application Support/Claude/claude_desktop_config.jsonWindows:%APPDATA%\Claude\claude_desktop_config.json配置内容很简单把上面写的 server.py 注册为 stdio 类型即可{ mcpServers: { excel-assistant: { command: python3, args: [/absolute/path/to/excel-mcp-server/server.py], env: { PYTHONIOENCODING: utf-8 } } } }配置完成后重启 Claude Desktop在设置里能看到excel-assistant已连接工具列表里会出现刚才注册的几个工具。如果没出现多半是 server.py 启动报错了往下翻到第 5 节排查方法。注意PYTHONIOENCODING环境变量很重要尤其是 Windows 上如果不强制 UTF-8 编码AI 返回的中文内容很容易在 stdio 通道里出现乱码或 json 解析错误。Cursor 的配置也差不多在项目根目录放一个.cursor/mcp.json或者直接在设置界面添加服务器都是同一套 JSON 结构。4.2 实测让 AI 自动整理多门店销售报表配置完成之后我挑了入住以来最想自动化的一件任务做实测“分析这个季度的销售明细表按区域汇总销售额标出退货率超过 10% 的门店并生成一份汇总 CSV 文件。”这句话听起来不复杂但按传统方式我至少要花十分钟。我盯着对话框看 AI 一步步操作第一步AI 调用了read_excel_structure读取表格结构看到了工作表名“Q3销售明细”和表头门店编码、所属区域、品类、销售额、退货量、退货率。第二步它调用了summarize_data参数为group_by所属区域, value_col销售额, agg_funcsum。返回了四个区域的汇总数字。第三步它又调用了read_excel_data我这里还注册了一个按条件读取单元格区域的工具定位到“退货率”列逐一筛选出超过 10% 的门店编码。第四步它把汇总结果和重点问题门店写成了 CSV 说明然后调用write_excel_data把最终结果存入新的区域销售汇总.xlsx。整个过程大概三十秒AI 自主决策、自主调用、自主完成。最关键的是它不再需要我提前把逻辑想清楚。我只需要说清楚“要什么”它自动拆解“怎么做”。传统脚本方案里那种“需求一变代码重写”的循环在这个工作流里直接消失了。4.3 扩展让 AI 按固定格式生成周报除了上面的临时查询我还把日常周报做成了固定套路。每周五下午我会丢给 AI 一句话“按上周的周报模板生成本周的销售周报。”这里的诀窍是在工具描述里加一个read_excel_data工具专门按指定区域读取数据。例如mcp.tool() def read_excel_range(file_path: str, sheet_name: str, min_row: int, max_row: int, min_col: int, max_col: int) - str: 读取指定区域内的所有单元格内容返回二维数组。 Args: file_path: Excel 文件路径 sheet_name: 工作表名 min_row/max_row: 读取的起始行和结束行 min_col/max_col: 读取的起始列和结束列 适合精确读取固定区域的明细数据。如果要了解文件结构请使用 read_excel_structure。 这个工具对“把表格内容当上下文传给 AI”特别有用。AI 模型本身看不到文件内容它只能通过工具返回的文本数据来“理解”表格。所以把读取范围限定在周报所需区域既能减少 token 消耗也能让 AI 更聚焦在关键数据上。使用之后的效果是我每周的周报时间从一小时压缩到了十分钟剩下十分钟主要用于核对而不是从零开始做。这也是 MCP 工作流最大的收益不是消灭人工而是消灭重复劳动。5. 踩坑记录与排查心得最后这部分我把这段时间实际开发和使用中踩到的坑、排查思路集中记录下来希望能帮大家省点时间。这些坑不一定每个人都会踩但碰到了没有头绪确实会很痛苦。5.1 Excel 文件占用与进程残留现象程序执行时报PermissionError: [Errno 13] Permission denied或者 openpyxl 加载文件时提示文件已被占用。原因Excel 桌面版打开着同一个文件或者上一个 Python 进程加载 WorkBook 后没有正确关闭文件被锁定。排查与解决第一步检查手动打开 Excel 窗口关闭所有正在预览的表格文件。第二步查 Python 进程残留。openpyxl的load_workbook拿到对象后一定要wb.close()否则在 Windows 上文件会一直处于锁定状态直到进程退出。上面代码里每个函数我都写了wb.close()这是深坑之后养成的习惯。如果你在用pandas或其他库还要注意 DataFrame 的中间对象是否持有文件句柄。顺手给个小技巧开发调试时可以给 Server 单独指定一个“测试文件副本”路径正常跑通了再去改真实文件。不然每次测试都要手动关 Excel实在太烦。5.2 路径校验与安全边界现象AI 请求读取一个你根本没打算让它碰的文件比如其他目录下的私人文档。原因AI 不理解现实世界的文件安全边界。你只跟它说“读取销售报表”它可能因为你的描述中出现了“对比上次的数据”而尝试去读桌面上所有文件名带“销售”的文件。解决我在_safe_path函数里做了白名单校验路径必须位于config.json中指定的目录内否则直接抛异常。这相当于是给 AI 的“手脚”上了个锁链。{ allowed_dirs: [ /Users/me/Documents/excel_workdir, /Users/me/Desktop/报表归档 ] }这个设计坚持执行之后再也没有出现过 AI 乱翻目录的情况。强烈建议每个自研 MCP Server 都做这样一层路径白名单无论你是个人用还是后面打算分享给别人用。5.3 中文字段与编码问题现象AI 传入的sheet_name明明是“销售明细”但程序报错找不到工作表。原因这个问题很隐蔽。有时候客户端比如 Windows 里的 Claude Desktop会用 GBK 编码启动 Python 子进程导致中文参数在 stdio 传输时变成乱码然后在 Server 内部被当成错误的工作表名。我在 JSON 配置里加了PYTHONIOENCODING: utf-8环境变量之后解决。另外还有一个小细节代码里所有文件读写尽量显式声明encodingutf-8避免依赖系统默认编码。5.4 工具调用超时与表格大小现象AI 等到“工具调用超时”或者返回的数据太大导致 Token 爆炸。原因read_excel_range把整个工作表的 5000 行数据一股脑读回来传给 AI文本量轻松上万 token。不仅慢而且容易让 AI 在处理上下文时迷失重点。解决一方面是工具描述里明确引导 AI“优先使用 summarize_data 做聚合不要读取明细数据”另一方面是在工具函数里设置读取上限。我实现时在read_excel_range里硬编码了max_row - min_row 200超过就报错提示“数据量过大请使用汇总工具”。这个限制对 AI 是好事——它被迫思考“我到底需要哪些数据”而不是无脑全量读取。我用下来AI 分析的行事风格反而更精确了。5.5 工具描述导致的误调用现象AI 明明只需要“求个总和”却调用了两次summarize_data之后又读了一遍原始表格。原因工具描述写得不够清晰AI 不确定summarize_data是不是能一步到位就重复调用多种工具自行验证。解决重新措辞工具描述把“一步到位”的语义写得更明确同时把重复调用会产生高成本耗时久、token 多的警告写进描述比如“注意一次调用即可获得最终结果无需重复调用”。实测下来AI 的调用次数明显减少。写在最后的一点感想这个项目从零到落地前后花了一个周末的时间。真正写代码的时间其实不长大部分时间都花在理解协议、调试路径权限、优化工具描述这些“看不见”的地方。但正是这些过程让我对公司里那些“引入 AI 提升效率”的项目有了更实在的理解——AI 的价值不在于替你思考而在于把你已经想明白的专业能力以规范化的方式交给一个能听懂自然语言的调度员。现在我每天处理 Excel 相关工作的方式已经彻底变了遇到新表格先丢给 Server 让它“看一眼结构”清楚了再决定怎么处理以前最烦的月度汇总已经变成了一个固定指令连我同事都开始找我要这个 Server 的配置想在自己电脑上跑起来。如果你也想试试 MCP我的建议是别从复杂的项目起步。先照这篇文章里的路子实现一个只有两三个工具的 Excel Server接进 Claude Desktop 跑通一次你立刻能感受到这个协议的奇妙之处。后面再想加点什么功能比如生成图表、格式美化、跨表关联都只是在工具列表里多注册几个函数的事。最后再分享一个小技巧工具函数的 docstring 不仅是给开发者看的更是给 AI 看的写得越像“给陌生人的使用手册”你的 MCP Server 就越聪明。这个经验值得你亲自实践验证一下。
