我做Excel处理这么多年一直有个挥之不去的痛点明明就是几行代码能搞定的事却总要一遍遍打开文件、选中区域、下拉公式、复制粘贴偶尔还要应对同事甩过来的“帮我查一下这个表”的需求。哪怕我把处理脚本写得再溜每次换个文件、改个条件都得手动改参数重新跑一遍。直到我花了两个晚上基于 MCP 协议写了第一个属于自己的 AI 工具节点把 Excel 处理流程整个交给了 AI 大模型来编排调度才算是真正把这件事从“重复劳动”变成了“发号施令”。这篇文章我就以“开发自己的第一个 MCP——用 AI 智能重构 Excel 处理工作流”为主线完整复盘一下从零到一的开发过程。内容会覆盖 MCP 的核心协议概念、开发环境搭建、服务器端工具封装、客户端接入配置以及几个真实场景下的实战效果。不管你是第一次听说 MCP 的初学者还是已经写完几个工具节点的老手这篇文章里都有可以直接参考的代码和配置也有我实际踩坑后总结出来的排查清单。1. 先搞清楚 MCP 到底解决了什么问题1.1 为什么我需要 MCP而不是继续写普通脚本过去处理 Excel 的常规套路是这样的写一个 Python 脚本用openpyxl或者pandas把文件读进来经过加工再输出成一个新文件。如果只是自己用这个套路完全没问题。但一旦场景变成“别人给你一个需求你帮忙处理一个表格”问题就来了——需求千变万化昨天是筛选某个月的数据今天是想把两列合并明天是要生成一张透视表。每次都去修改脚本里的参数不仅繁琐而且很容易把脚本改得面目全非。我尝试过用命令行参数把这些东西都做成可选项但每个人都命令行交互门槛太高。后来我试过 Web 表单但为了一个表格处理任务搭一个前后端项目维护成本又太重。直到我接触了 MCP才意识到这才是把“工具能力”和“AI 智能调度”结合的正解把 Excel 处理能力封装成一个可以复用的工具服务器让 AI 大模型作为大脑根据自然语言指令去调用合适的工具、组合工具流程、自己决定参数最终完成整条工作流。MCP 的全称是 Model Context Protocol模型上下文协议。它的定位非常像一个“USB-C 接口”——你不需要关心不同的设备用什么接口、什么电压、什么协议只要它们都支持 USB-C一个口就能给手机充电、传数据、输出视频。MCP 在 AI 世界里做的事情一模一样不管前端是大模型聊天客户端、IDE 插件还是自动化 Agent只要它支持 MCP就能通过统一协议连接我写的 Excel 工具服务无需专门为每个 AI 产品定制集成方式。1.2 MCP 的架构和三个核心角色先快速过一下 MCP 的架构这样后面写代码的时候你会很清楚自己在做什么。一套完整的 MCP 体系由三层角色组成我用自己的话翻译一下Host宿主用户直接面对的程序比如 Claude Desktop、Cherry Studio、VS Code 里的 AI 插件、甚至你自己开发的 Agent 应用。它负责收集用户指令、调用大模型、展示结果。Client客户端运行在 Host 内部负责和远端或本地的 MCP Server 建立连接发送请求接收响应。一个 Host 里通常可以配置多个 Client分别连不同的服务器。Server服务器我这次开发的核心部分。它把 Excel 的读取、写入、分析、汇总等能力以“工具Tool”的形式暴露出来同时可以声明“资源Resource”和“提示词模板Prompt”。Server 本身不需要关心用户说什么它只需要把自己能做好的事情罗列清楚等内容调用。协议层主要定义了三种能力原语工具Tools、资源Resources和提示词模板Prompts。我在 Excel 工作流里主要用工具因为工具是“主动执行某个动作”的接口比如“打开文件”“写入单元格”。资源偏重于“提供上下文数据”比如把一个 Excel 文件的路径注册为资源供模型读取提示词模板则是预置操作指令比如“汇总数据时遵循这样的步骤”。开发第一个 MCP 时建议专注做工具把一条路径做通做熟资源模板以后用得到再补充。从传输方式来说本地开发最常用的是stdio也就是在配置文件里指定启动命令Host 直接通过标准输入输出和 Server 进程通信。如果你自己有服务器也可以做成streamable HTTP模式部署到远程。不过第一次开发建议先走 stdio调试起来简单直接。2. 开发环境与整体设计思路2.1 技术选型为什么是 Python FastMCP openpyxl pandas确定技术栈的时候我心里有几个候选TypeScript 版的人 TinaMCP SDK 也很成熟但考虑到我要处理 ExcelPython 生态里pandas和openpyxl是我最熟悉的组合处理表格数据非常顺手所以语言选 Python。在 Python 的 MCP 开发包里最常用的是官方mcpSDK它提供了一个轻量封装层叫FastMCP用装饰器就能把普通函数注册成工具大幅降低了样板代码量。如果你没有特殊要求直接用FastMCP就行它内部会自动处理协议握手、工具 schema 生成、请求分发这些事情。唯一要注意的是 Python 版本建议 3.10 以上我开发时用的 3.12协议相关依赖对高版本支持更好。Excel 操作方面按需求分两个层级对.xlsx格式的读写用openpyxl它可以精细控制单元格、合并、样式、公式适合写入结构化报表。做数据清洗、筛选、分组聚合时用pandas更高效因为它内部是向量化计算处理几千几万行毫无压力。对.xls老格式pandas底层依赖xlrd来读取但写入.xls基本不用了遇到这种情况建议让用户先转成.xlsx或者直接用LibreOffice命令行批量转换。数据和工具层面还有个很关键的取舍MCP 工具的函数签名要尽量简单。为什么因为大模型需要根据你的函数名、参数名和 docstring 来决定怎么调用签名越复杂模型就越容易传错参数。所以我在设计工具时刻意把参数控制在三到五个能合并的参数就合并。比如“读取某个 Excel 的某个工作表”我就合并成一个read_sheet(file_path, sheet)工具而不去单独做“列出所有工作表”再“读取指定表”的两步调用让模型用最少步骤完成操作。2.2 项目结构与模块划分实际开发时我保持了极简的项目结构就三个文件加一个配置文件excel-mcp/ ├── pyproject.toml ├── excel_mcp/ │ ├── __init__.py │ ├── server.py # MCP 服务器入口注册所有工具 │ └── excel_ops.py # Excel 底层操作封装 └── README.md这么拆的原因是excel_ops.py放纯函数用openpyxl和pandas写具体的表格处理逻辑不依赖 MCP SDK。这样一来即使以后不用 MCP 了这套函数也能直接给脚本或 Web 服务调用。server.py只做一件事导包、初始化FastMCP实例、用mcp.tool()把函数注册为工具、启动运行。pyproject.toml管理项目依赖和入口命令用uv打包后可以直接在配置里写uv run excel-mcp启动。初学时最容易犯的错误是把 Excel 处理逻辑和 MCP 协议逻辑全写在一个文件里看起来内容不少但后面加一个工具、调整一个函数整个文件就乱了。注册工具只是薄薄一层核心逻辑全放在纯函数里这个习惯越早养成越好。3. 从零开始写 Excel MCP 服务器3.1 初始化项目与安装依赖我使用uv来管理项目速度和便捷性都比pip更好尤其后面接入 Claude Desktop 时可以直接让 MCP 用uv run拉起项目省去了手动建虚拟环境的麻烦。初始化命令如下mkdir excel-mcp cd excel-mcp uv init --python 3.12然后添加依赖uv add mcp openpyxl pandasmcp包会带来所有协议相关依赖openpyxl负责读写.xlsxpandas负责数据分析和聚合。国内网络环境不好时如果下载慢可以换成对应镜像源这个就不展开了装好这套依赖环境就齐了。接着在pyproject.toml里把项目入口写成命令行工具这样后面配置 MCP 时可以直接用excel-mcp命令启动[project.scripts] excel-mcp excel_mcp.server:main写代码之前我习惯先把接口想清楚。既然是 AI 智能重构 Excel 工作流那 AI 会调用哪些工具我梳理了最常用的几个能力读取 Excel 文件中的某个工作表返回表格内容。列出 Excel 文件中包含的所有工作表名称。对表格进行筛选、排序、统计并返回结果摘要。将处理后的数据写成一个新的 Excel 文件。把 DataFrame 形式的数据转换成结构化文本方便 AI 读取分析。3.2 读取与基础信息查询工具的实现先写excel_ops.py里的核心函数。第一个是读取工作表内容我用pandas读取后转成 JSON 字符串返回。注意在返回给模型之前必须把DataFrame转成可序列化的格式否则后面智能体会直接报错。# excel_mcp/excel_ops.py from pathlib import Path import json import pandas as pd from openpyxl import load_workbook def read_excel_sheet(file_path: str, sheet: str Sheet1, max_rows: int 200) - str: 读取 Excel 文件中指定工作表的内容。 返回一个 JSON 字符串包含表头、行数和前 max_rows 行数据。 path Path(file_path) if not path.exists(): raise FileNotFoundError(f文件不存在: {file_path}) df pd.read_excel(path, sheet_namesheet, engineopenpyxl) # 限制返回行数避免超出模型上下文窗口 sample df.head(max_rows) result { file: file_path, sheet: sheet, columns: list(df.columns), total_rows: len(df), data: sample.fillna().astype(str).to_dict(orientrecords), } return json.dumps(result, ensure_asciiFalse, indent2)这里fillna()很关键因为 Excel 表格很容易出现空单元格如果不填充就直接序列化NaN会被转成null模型读取时可能产生歧义。我用空字符串统一替换掉保证返回数据的整洁。第二个是列表所有工作表名字。def get_sheet_names(file_path: str) - list[str]: 返回 Excel 文件中所有工作表的名称列表 wb load_workbook(file_path, read_onlyTrue) try: return wb.sheetnames finally: wb.close()注意这里用了read_onlyTrue对于大型工作簿能节省大量内存。而且我习惯将 workbook 关闭写在finally里避免占用文件句柄导致 Windows 平台下删除文件失败。3.3 数据筛选和统计分析工具接下来是筛选和聚合工具。我直接利用pandas的query表达式做条件筛选因为query的语法接近自然语言比如月份 三月 and 销售额 10000模型更容易生成正确的参数。def filter_excel( file_path: str, sheet: str, condition: str, output_path: str ) - str: 根据条件筛选 Excel 数据并返回筛选结果摘要。 条件使用 pandas query 语法例如 销售额 10000 城市 上海 and 季度 Q1 df pd.read_excel(file_path, sheet_namesheet, engineopenpyxl) try: filtered df.query(condition) except Exception as e: raise ValueError(f筛选条件不合法: {condition}, 错误: {e}) result { matched_count: len(filtered), columns: list(df.columns), sample: filtered.head(50).fillna().astype(str).to_dict(orientrecords), } if output_path: filtered.to_excel(output_path, indexFalse) result[saved_to] output_path return json.dumps(result, ensure_asciiFalse, indent2)这里我做了个重要的安全设计如果用户指定了output_path才真正写入文件如果没有指定工具只返回筛选结果的摘要不会产生任何副作用。这是因为 AI 在调用工具时经常会在用户还没有明确要求“保存成文件”的情况下自作主张地写文件而这种行为一旦发生很容易把一个原始文件覆盖掉。所以我的设计原则是默认无副作用保存动作必须显式触发。聚合统计工具也一样接收group_by和agg_expr参数返回分组后的聚合结果def aggregate_excel( file_path: str, sheet: str, group_by: str, agg: str sum, value_col: str ) - str: 对 Excel 数据按指定列分组聚合支持 sum/mean/count/min/max。 示例 group_by城市, aggsum, value_col销售额 返回每个城市的销售额总和。 df pd.read_excel(file_path, sheet_namesheet, engineopenpyxl) if group_by not in df.columns: raise ValueError(f分组列不存在: {group_by}) if agg count: grouped df.groupby(group_by).size().reset_index(namecount) else: if value_col not in df.columns: raise ValueError(f聚合列不存在: {value_col}) grouped df.groupby(group_by)[value_col].agg(agg).reset_index() return json.dumps( grouped.fillna().astype(str).to_dict(orientrecords), ensure_asciiFalse, indent2 )这个工具的价值在于——你不再需要知道pivot_table和groupby怎么用只要告诉 AI “按城市汇总一下销售额”AI 就会自动决定调用聚合函数并传入正确的参数。当然为了让 AI 更容易选对参数我特意把聚合操作的类型做成了sum/mean/count/min/max五个枚举避免模型自由发挥产生不支持的聚合方式。3.4 新建 Excel 和写入数据工具最后一个核心工具是“把 AI 分析结果或清洗后的数据保存为 Excel”。考虑到 AI 生成结构化的表格数据时往往以 JSON 形式返回我在工具里设计成接收一个 JSON 字符串然后解析并写入。def create_excel_from_json(json_data: str, output_path: str) - str: 将 JSON 数组写入新的 Excel 文件。 json_data 示例[{姓名: 张三, 销售额: 100}, {姓名: 李四, 销售额: 200}] import json records json.loads(json_data) if not isinstance(records, list) or len(records) 0: raise ValueError(JSON 数据必须是非空数组) df pd.DataFrame(records) df.to_excel(output_path, indexFalse) return json.dumps({saved_to: output_path, rows: len(df), columns: list(df.columns)})这里有个细节pd.DataFrame(records)会自动根据字典的键生成列顺序。如果不同行之间的键不一致生成的列顺序可能不符合预期。稳妥起见可以在生成 DataFrame 后手动重排列df df[list(records[0].keys())]确保列的顺序以第一条记录的键顺序为准。3.5 注册到 FastMCP 服务器并启动底层的 Excel 操作函数写完后server.py就简单多了。我用FastMCP初始化一个名叫excel-agent的服务然后用mcp.tool()把函数逐个注册上去。# excel_mcp/server.py from mcp.server.fastmcp import FastMCP from excel_mcp.excel_ops import ( read_excel_sheet, get_sheet_names, filter_excel, aggregate_excel, create_excel_from_json, ) mcp FastMCP(excel-agent) mcp.tool() def read_sheet(file_path: str, sheet: str Sheet1, max_rows: int 200) - str: 读取 Excel 文件的指定工作表返回表格数据 JSON。 return read_excel_sheet(file_path, sheet, max_rows) mcp.tool() def list_sheets(file_path: str) - list[str]: 列出 Excel 文件中所有工作表名称。 return get_sheet_names(file_path) mcp.tool() def filter_data(file_path: str, condition: str, sheet: str Sheet1, output_path: str ) - str: 按条件筛选 Excel 表格数据条件使用 pandas query 语法。 return filter_excel(file_path, sheet, condition, output_path) mcp.tool() def aggregate_data(file_path: str, group_by: str, agg: str sum, value_col: str , sheet: str Sheet1) - str: 对 Excel 数据按列分组聚合sum/mean/count/min/max。 return aggregate_excel(file_path, sheet, group_by, agg, value_col) mcp.tool() def save_excel(json_data: str, output_path: str) - str: 将 JSON 数组保存为新的 Excel 文件。 return create_excel_from_json(json_data, output_path) def main(): mcp.run() if __name__ __main__: main()这里有一个小细节值得注意注册成工具后函数名会变成工具名。read_excel_sheet这样带下划线的名字虽然能用但 AI 自然语言匹配工具名时往往是连字符或缩写更友好。所以注册时我用了更简洁的read_sheet、list_sheets、filter_data这些名称函数本身的 docstring 也要写清楚“这个工具是干什么的、参数含义是什么、有什么限制”因为 docstring 最终会成为工具 schema 的描述直接送给模型阅读。描述不够清晰的工具等于让瞎子引路。启动服务器时如果是本地 stdio 模式直接执行mcp.run()即可它会等待标准输入上的协议握手消息。我在开发调试时会先加一段打印日志到 stderr方便观察协议过程import sys mcp.run()FastMCP默认的传输模式就包括了 stdio 的支持本地接入不需要额外参数。如果你想用 HTTP 暴露服务mcp.run(transportstreamable-http)就行了不过线上部署还需要考虑鉴权和网络安全新手阶段先不碰。4. 把 MCP 接入 AI 客户端以 Claude Desktop 和 Cherry Studio 为例4.1 Claude Desktop 的 MCP 配置写完了服务器下一步是让 AI 客户端能够发现并调用它。我最开始用的是 Claude Desktop它原生支持 MCP Server 配置。在 macOS 上配置文件位于~/Library/Application Support/Claude/claude_desktop_config.jsonWindows 上则在%APPDATA%\Claude\claude_desktop_config.json。配置内容如下{ mcpServers: { excel-agent: { command: uv, args: [ run, --directory, /绝对路径/到/excel-mcp, excel-mcp ] } } }这段配置的意思让 Claude Desktop 通过uv run命令把我的项目跑起来然后通过标准输入输出和我这个 MCP 服务器通信。填配置时要特别注意路径都是绝对路径不能用~代替否则可能找不到项目目录。excel-mcp是我在pyproject.toml里定义的命令行入口我觉得这种启动方式最干净不用手动去激活虚拟环境。配置完成后重启 Claude Desktop在界面上应该能看到一个连接成功的状态。如果失败了点击那个感叹号就能看到日志定位问题最常见的错误就是uv命令不在全局 PATH 里或者路径写错了。4.2 Cherry Studio 和 VS Code 等客户端的接入除了 Claude Desktop我实际用得更多的是 Cherry Studio因为它对国内开发者更友好并且可以自由选择接入各种大模型 API。在 Cherry Studio 的设置界面里有一个 MCP 服务器的管理入口同样是在 JSON 配置里维护连接列表。{ mcpServers: { excel-agent: { command: python, args: [-m, excel_mcp.server] } } }前提是python命令所在的虚拟环境已经装好了mcp、openpyxl、pandas这几个依赖。如果你不想用绝对路径可以把启动脚本封装成一个全局命令或者直接用uv run。用python -m的方式最轻量适合快速验证服务能否跑通。对于 VS Code 里的 AI 编程插件比如 Cline、Continue 这类配置大同小异。有些插件支持在 UI 图形化添加 MCP 服务器只需填名称和启动命令即可。本质上只要 Host 支持 MCP 客户端同一个 Server 可以同时接入多种客户端。这就体现了统一协议的好处——写一次到处复用。如果你以后要走共享 MCP 注册中心的方式联网获取 MCP 服务器也不用改excel-agent的代码只要协议兼容即可。也就是我一直强调的MCP 把“能力提供”和“智能调度”解耦了我这个 Excel 处理器以后随时可以挂到别的 AI 前端里。4.3 验证连接让 AI 自己发现工具并调用配置好之后打开客户端对话框我通常先用一句话测试“读取桌面上sales.xlsx文件里Sheet1的前 5 行。”然后大模型会通过工具列表发现read_sheet自动解析文件路径和 sheet 名发起工具调用并把我的 JSON 返回内容整理成自然语言。这个过程非常有意思——我能看到 AI 按某种“思维链”的方式先确认参数再调用工具最后总结结果。第一次测试成功时我的感受是这就好像给 AI 装上了一双手它终于不只是“聊”文件内容而是真实地“读”文件内容了。这种从“说”到“做”的跨越才是 MCP 重构工作流的核心魅力所在。5. 真实场景复盘AI 如何重构我的 Excel 工作流5.1 场景一批量汇总多个 Excel 文件的销售数据以前处理月底销售汇总我要写 Python 循环把所有分区的 Excel 读进来concat之后按城市分组求和再输出一张汇总表。这个流程倒是不难但每次换路径、换月份都得改脚本里的字符串。现在我的操作方式是在 AI 对话框直接说“读取C:\data\sales\目录下的所有.xlsx文件把所有数据合并后按城市汇总销售额另存为summary.xlsx。”因为我的 MCP 服务器目前提供的是单个文件操作接口AI 在多文件汇总时有两种策略一是逐个调用read_sheet把所有内容读出来后自己用代码生成汇总二是它会发现自己处理不了“读取目录所有文件”这种批量操作就会引导用户要么优化工具增加目录支持要么先自行合并文件。这里我采用的是更务实的做法再增加一个“合并并汇总”的扩展工具专门接收folder_path参数用pandas配合glob读取文件夹下所有 Excel 文件横向拼接后统一聚合。一句话命令批量完成工作流这才是“重构”的威力。def merge_and_aggregate(folder_path: str, group_by: str, agg: str sum, value_col: str , output_path: str ) - str: 合并文件夹下所有 .xlsx 文件并按指定列分组聚合。 import glob files glob.glob(str(Path(folder_path) / *.xlsx)) if not files: raise ValueError(f文件夹中不存在 Excel 文件: {folder_path}) frames [pd.read_excel(f, engineopenpyxl) for f in files] df pd.concat(frames, ignore_indexTrue) if agg count: grouped df.groupby(group_by).size().reset_index(namecount) else: grouped df.groupby(group_by)[value_col].agg(agg).reset_index() result grouped.fillna().astype(str).to_dict(orientrecords) if output_path: grouped.to_excel(output_path, indexFalse) return json.dumps({aggregated: result, saved_to: output_path}, ensure_asciiFalse, indent2) return json.dumps({aggregated: result}, ensure_asciiFalse, indent2)这个工具的 docstring 要特别写清楚“文件夹路径下所有 xlsx 会被合并”文档不写清楚模型很容易把它当成单文件工具去读。实际开发中工具描述是接口设计的一部分跟代码同等重要。5.2 场景二数据清洗和格式统一Excel 工作流里最烦人的不是分析而是清洗。比如同事发来的表里“城市”字段一会是“上海”一会是“上海市”金额列里有的带逗号有的是文本格式还有一堆多余的空白行。以前我需要写一堆正则和替换逻辑现在只需要对 AI 说“把表格里城市列的上海市统一成上海把金额列转成数字去掉所有空行另存为cleaned.xlsx。”关键在于我的 MCP 服务器泡制了clean_data这样的工具利用pandas的replace和to_numeric能力把清洗步骤封装成可配置参数。AI 会根据自然语言自动转化成调用命令。虽然清洗规则过于复杂时AI 会开始发挥创造力所以我尽量让工具接收一个映射字典JSON 字符串来描述替换规则而不是让 AI 自由做正则。正则表达式交给模型去生成很容易出错一旦出错表格就被改得面目全非所以宁可多花几步也要让规则尽量透明、可控。5.3 场景三自动生成图表数据和格式化报告Excel 处理的最终目的往往是产出决策依据。有一次经理让我分析各产品线的季度增长还要附上简明结论。这个任务如果人工做至少要切好几个 Sheet数据透视、环比计算、图表数据表。现在我的流程是先把原始数据表交给 AI 读取然后用自然语言描述分析需求AI 通过我的filter_data和aggregate_data做分组统计再让我现有的save_excel直接生成一张带干净数据表的结果文件。我甚至写过一个generate_markdown_report工具让 AI 把聚合结果渲染成 markdown 表格加结论直接粘到邮件里。这样做的好处是Excel 负责存储结构化数据AI 负责生成可读性结论各司其职整个流程完全打通。这个场景充分体现了我前面说的“工作流重构”——AI 不是简单地替你做一步操作而是把“分析思路”“工具调用”“结果呈现”串成了一条完整的链。6. 开发期踩坑记录与排查技巧6.1 工具参数不匹配AI 乱传参数怎么办开发 MCP 工具时最常遇到的问题就是 AI 调用工具时参数对应不上。比如我明明定义了一个sheet参数它却传了个sheetname或者把我给的文件路径加了一层多余引号。这类问题通常是因为工具名称和参数名不够直观或者 docstring 描述不够清楚。解决办法就是我前面说的参数名尽量口语化工具描述里给出示例。另外函数参数可以设置默认值能减少模型传参的负担。但要注意如果参数设了默认值模型可能会省略它所以关键参数别给默认值比如文件路径次要参数可以给默认值。6.2 返回内容太长撑爆上下文窗口有一次我让 AI 读取一个几万行的表格返回的 JSON 串直接超出上下文窗口AI 就开始“胡言乱语”。排查后发现问题出在read_sheet工具没有限制行数。我给所有读取类工具都加了max_rows参数默认 200 行并明确告诉模型“查询结果仅显示前 200 行如需更多数据请使用筛选工具”。这样既控制了上下文长度又引导模型先用条件筛选缩小数据范围再读取。对于数据分析场景通常不需要把全量数据一次读入先让模型看表头和样例确定筛选条件后再调其他工具反而会更准确。6.3 Excel 文件被锁定或占用导致写入失败在 Windows 环境下如果 Excel 程序里打开了目标文件再让 MCP 工具去写入就会报PermissionError。这个问题在第一次实际使用中踩到过我的解决方式是在工具层做一层重试封装第一次写入失败后抛出明确的中文错误提示告诉用户“文件被占用请关闭 Excel 窗口后重试”。同时让 AI 把错误信息原样回复给用户而不是自己默默重试或甩锅。工具稳定性的价值就在这种细节里用户不关心你是不是 MCP只关心任务到底成没成。6.4 中文路径和编码问题中文路径在国内太常见了。pandas和openpyxl都能处理好 Unicode 路径但有一点要注意工具返回的 JSON 里如果有中文必须用ensure_asciiFalse否则模型收到的会是\u4e2d这种转义字符虽然大多数模型能解码但可读性差也容易出问题。我在所有序列化位置都统一加了ensure_asciiFalse配合indent2让 AI 能读到清晰的中文。另外代码文件头部记得加# -*- coding: utf-8 -*-虽然 Python 3 默认就是 UTF-8但在 Windows 上配合特定编码环境时这一行能少掉很多奇怪的乱码问题。6.5 排查 MCP 网络连接和日志问题当 MCP 连接不上时第一件事不是看代码而是看日志。Claude Desktop 的配置界面能直接看到每个 MCP Server 的运行日志Cherry Studio 的 MCP 管理页也有连接状态和错误信息。如果是用 VS Code 插件一般会在输出面板打印 MCP 调用日志。常见的故障模式有几种一是启动命令写错比如uv没安装或者全局路径不对二是项目依赖没装全导致 import 失败三是 Server 启动后没有任何输出Host 握手超时。这些可以先用命令行手动敲一遍启动命令确认能否正常启动再做协议层诊断。如果启动命令没问题再用 MCP Inspector 做深度调试那是官方提供的可视化调试工具能一眼看清每个工具调用的情况。6.6 安全边界防止 AI 乱写乱删最后聊一个很多人忽略但非常重要的问题工具的安全性。让 AI 操控 Excel 处理本质上是把一部分文件系统操作权限交给了模型。如果你把所有函数都注册成工具AI 可能会被引导去删除文件、覆盖原表。我在设计时就约定了几条原则所有工具只支持读取和另存为操作不提供删除、覆盖原文件的工具。保存类工具必须指定output_path且如果目标已存在工具直接报错要求用户换个文件名。敏感操作比如读取特殊目录、批量合并文件夹的 docstring中明确提醒模型“操作需用户确认”。这几条原则放到代码里很简单但能避免很多本不该发生的数据事故。MCP 赋予 AI 的能力越强边界意识就越重要这也是开发这类工具时最需要养的思维习惯。7. 从第一个 MCP 到什么时候该考虑扩展框架写完这个 Excel MCP 之后我又给它增加了导出 CSV、合并多个 Sheet、自动化报表生成等工具。一个很自然的疑问是我要不要马上把它升级成一个“MCP 服务器管理框架”我的建议是不要急于过度设计。第一版保持简单和透明工具数量控制在十个以内函数签名尽量统一用同一套代码规范维护。当你发现自己需要往同一个服务器上挂五六个不同领域的工具组时再考虑模块化拆分或引入更丰富的 MCP 中间件层为时未晚。我现在的开发习惯是每新增一个 Excel 处理场景先变成excel_ops.py里的一个纯函数再在server.py里注册成工具最后用一句话写进 README 发到群里给同事当“咒语”用。他们甚至不需要知道我用了什么协议只要告诉我需求AI 就能帮我完成。这种开发节奏非常舒服也让我真正体会到工具协议不在于多复杂而在于能多么顺滑地嵌入现有工作流。如果你也想尝试按照文章里的步骤把一个最简单的读取工具跑通剩下的就是一场“给 AI 配遥控器”的快乐迭代。选择一个你每天都要重复的 Excel 处理场景把它变成第一个 MCP 工具的起点——然后你会发现原来 AI 重构工作流的门槛比自己想象的低太多了。