Excel MCP Server 实战指南让 AI Agent 通过 MCP 协议直接创建、读取与修改 Excel 工作簿【免费下载链接】klavisKlavis AI: MCP integration platforms that let AI agents use tools reliably at any scale项目地址: https://gitcode.com/GitHub_Trending/kl/klavisExcel MCP Server 是 Klavis 开源仓库mcp_servers/local/excel目录下提供的一个 Model Context ProtocolMCP服务端实现它允许 AI Agent 在不安装 Microsoft Excel 的情况下完成工作簿创建、数据读写、公式应用、格式设置、图表与数据透视表生成等操作。本文以该目录的 README.md 为骨架结合 TOOLS.md 工具清单与src/excel_mcp源码实现完整讲解三种传输方式的配置、环境变量与文件路径处理、全部工具的能力与参数以及底层校验与错误处理机制帮助你在本地或远程环境中快速接入并可靠地使用这一 Excel 操作能力。项目定位与核心能力Excel MCP Server 是一个基于 Python 的 MCP 服务端底层使用openpyxl读写.xlsx文件通过FastMCP暴露工具接口。其核心设计目标是让 AI Agent 像操作本地 Excel 一样创建、读取、更新工作簿与工作表而无需安装微软 Office 套件。从 pyproject.toml 可以确认其技术栈与版本要求项值包名excel-mcp-server当前仓库版本 0.1.7Python 要求3.10核心依赖mcp[cli]1.10.1、fastmcp2.0.0,3.0.0、openpyxl3.1.5、typer0.16.0入口命令excel-mcp-server excel_mcp.__main__:app根据 README.md 的功能列表该服务覆盖以下能力域Excel 基础操作创建工作簿、工作表读取与更新数据数据处理公式、格式化、图表、数据透视表与 Excel 原生表格数据校验对区域range、公式与数据完整性提供内置校验格式化字体样式、颜色、边框、对齐与条件格式表格操作创建并管理带自定义样式的 Excel 表格图表创建折线图、柱状图、饼图、散点图、面积图等数据透视表面向数据分析的动态透视表生成工作表管理复制、重命名、删除工作表传输方式同时支持 stdio、SSE已标记废弃与 streamable HTTP 三种传输部署形态既可作为本地进程运行也可作为远程服务部署。快速开始三种传输方式的启动与配置服务提供了三个 Typer 子命令分别对应三种传输模式入口定义在main.pyuvx excel-mcp-server stdio # 本地 stdio 模式 uvx excel-mcp-server sse # SSE 模式已废弃 uvx excel-mcp-server streamable-http # 流式 HTTP 模式远程推荐1. Stdio 传输本地使用stdio 模式适合直接在本地 MCP 客户端如 Claude Desktop、Cursor 等中通过子进程方式启动。服务端与客户端之间通过标准输入/输出进行 MCP 消息通信因此该模式下服务端不能向 stdout 写入任何非 MCP 协议的日志详见下文日志与协议约束。{ mcpServers: { excel: { command: uvx, args: [excel-mcp-server, stdio] } } }2. SSE 传输已废弃SSEServer-Sent Events传输曾在远程场景中广泛使用README 已明确标注其Deprecated已废弃状态新项目建议直接采用 streamable HTTP。若仍需连接旧服务可这样配置{ mcpServers: { excel: { url: http://localhost:8000/sse } } }3. Streamable HTTP 传输远程连接推荐streamable HTTP 是当前 MCP 标准推荐的远程传输方式服务端监听 HTTP 端口并提供/mcp端点{ mcpServers: { excel: { url: http://localhost:8000/mcp } } }需要特别指出的是上述两个 JSON 示例中的端口8000是 README 中的示例值。从 server.py 的实际实现看FastMCP初始化时端口的默认值是8017mcp FastMCP( excel-mcp, hostos.environ.get(FASTMCP_HOST, 0.0.0.0), portint(os.environ.get(FASTMCP_PORT, 8017)), instructionsExcel MCP Server for manipulating Excel files )因此如果未显式设置FASTMCP_PORT客户端应连接http://host:8017/mcp或http://host:8017/sse。环境变量与文件路径处理这是使用该服务时最容易踩坑的部分README 与源码在路径语义上给出了明确区分。远程模式SSE / Streamable HTTP下的 EXCEL_FILES_PATH当以 SSE 或 streamable HTTP 协议运行时服务端必须设置EXCEL_FILES_PATH环境变量用于告知服务端从哪里读取、向哪里写入 Excel 文件如果未设置则默认使用./excel_files。对应实现位于 server.py 的run_sse()与run_streamable_http()两者都会读取该环境变量并自动创建目录EXCEL_FILES_PATH os.environ.get(EXCEL_FILES_PATH, ./excel_files) os.makedirs(EXCEL_FILES_PATH, exist_okTrue)同时可通过FASTMCP_PORT控制监听端口未设置时默认8017。此外从源码还可以看到服务端还支持FASTMCP_HOST环境变量默认绑定0.0.0.0方便远程访问。Windows PowerShell 示例$env:EXCEL_FILES_PATHE:\MyExcelFiles $env:FASTMCP_PORT8007 uvx excel-mcp-server streamable-httpLinux/macOS 示例EXCEL_FILES_PATH/path/to/excel_files FASTMCP_PORT8007 uvx excel-mcp-server streamable-httpStdio 模式下的路径语义与远程模式不同stdio 模式下无需在服务端设置EXCEL_FILES_PATH每次工具调用时由客户端直接传入文件路径服务端按调用中的路径执行操作。这一设计在源码中有完整的体现。server.py中的get_excel_path()函数负责路径解析server.py如果传入的是绝对路径直接返回该路径如果传入的是相对路径且EXCEL_FILES_PATH为None即 stdio 模式会抛出ValueError提示必须使用绝对路径如果传入相对路径且处于远程模式则基于EXCEL_FILES_PATH拼接出完整路径。这套逻辑意味着在本地 stdio 集成中AI Agent 对文件位置拥有完全的控制权而在远程部署中所有文件操作都被限制在服务端指定的根目录内便于统一管理与权限收敛。工具全景从工作簿到单元格的完整操作矩阵完整的工具清单与签名记录在 TOOLS.md 中而 server.py 中的mcp.tool()装饰器对应着每个工具的运行时注册。以下按功能域逐一展开。工作簿与工作表操作工具签名说明create_workbookcreate_workbook(filepath: str) - str新建 Excel 工作簿返回创建成功的文件路径create_worksheetcreate_worksheet(filepath, sheet_name) - str在已有工作簿中新建工作表get_workbook_metadataget_workbook_metadata(filepath, include_ranges: bool False) - str获取工作簿元数据include_rangesTrue时附带各工作表已使用区域如A1:D20copy_worksheetcopy_worksheet(filepath, source_sheet, target_sheet) - str在工作簿内复制工作表delete_worksheetdelete_worksheet(filepath, sheet_name) - str删除工作表rename_worksheetrename_worksheet(filepath, old_name, new_name) - str重命名工作表在源码层面create_workbook的实现位于 workbook.py它创建openpyxl.Workbook实例、将默认的Sheet重命名为Sheet1并在保存前自动创建父目录path.parent.mkdir(parentsTrue, exist_okTrue)。get_workbook_info则返回文件名、工作表列表、文件大小与修改时间并可按需计算每个工作表的使用范围A1:{最大列字母}{最大行号}。数据读写写入数据write_data_to_excel( filepath: str, sheet_name: str, data: List[Dict], start_cell: str A1 ) - strdata为要写入的数据TOOLS.md 描述为字典列表源码中实际按行处理的二维列表start_cell指定写入起始单元格默认A1。从 data.py 的实现看write_data对 sheet 名称做了智能处理未指定时写入活动工作表指定的表不存在时会自动创建随后通过parse_cell_range校验起始单元格格式再逐行逐列写入并保存。读取数据read_data_from_excel( filepath: str, sheet_name: str, start_cell: str A1, end_cell: str None, preview_only: bool False ) - strend_cell可选不传时自动扩展到工作表的数据边界返回值为 JSON 字符串包含区域信息、工作表名以及每个单元格的地址、值、行号、列号。值得关注的是读取能力的深度read_excel_range_with_metadatadata.py会在读取时为每个单元格附带校验元数据validation字段即当单元格存在数据校验规则时一并返回没有校验时返回{has_validation: False}。这意味着 AI Agent 在写入前就能感知目标单元格的约束条件。格式化与合并format_range是参数最丰富的工具之一format_range( filepath: str, sheet_name: str, start_cell: str, end_cell: str None, bold: bool False, italic: bool False, underline: bool False, font_size: int None, font_color: str None, bg_color: str None, border_style: str None, border_color: str None, number_format: str None, alignment: str None, wrap_text: bool False, merge_cells: bool False, protection: Dict[str, Any] None, conditional_format: Dict[str, Any] None ) - str它覆盖了字体加粗/斜体/下划线/字号/颜色、背景色、边框样式与颜色、数字格式、对齐方式、自动换行、合并单元格、单元格保护与条件格式等能力。其底层实现在 formatting.py 中由server.py的format_range工具转发调用。合并相关的三个独立工具工具签名说明merge_cellsmerge_cells(filepath, sheet_name, start_cell, end_cell) - str合并单元格区域unmerge_cellsunmerge_cells(filepath, sheet_name, start_cell, end_cell) - str取消合并get_merged_cellsget_merged_cells(filepath, sheet_name) - str获取工作表内已合并的区域公式操作工具签名说明apply_formulaapply_formula(filepath, sheet_name, cell, formula) - str向单元格写入公式带校验validate_formula_syntaxvalidate_formula_syntax(filepath, sheet_name, cell, formula) - str仅校验公式语法不写入apply_formula的执行链路在源码中非常清晰calculations.py先校验单元格引用是否合法再确保公式以开头随后调用validate_formula做语法与安全性检查通过后写入并保存。而 validation.py 中的validate_formula实现了两层校验语法层公式必须以开头括号必须配对不允许未闭合或多余的右括号安全层通过正则提取函数名黑名单拦截INDIRECT、HYPERLINK、WEBSERVICE、DGET、RTD等易被用于注入或外联的危险函数。此外validate_formula_in_cell_operation即validate_formula_syntax与apply_formula共用的底层校验还会解析公式中引用的单元格/区域并对比单元格现有内容返回valid、matches、current_formula等详细信息供 Agent 判断公式是否已与单元格内容一致。图表创建create_chart( filepath: str, sheet_name: str, data_range: str, chart_type: str, target_cell: str, title: str , x_axis: str , y_axis: str ) - strchart_type支持line折线、bar柱状、pie饼图、scatter散点、area面积data_range为图表数据来源区域target_cell指定图表锚定位置。图表底层实现在 chart.py 中源码揭示了比工具签名更丰富的细节支持通过SheetName!A1:B2语法跨工作表引用数据区域支持style字典内部默认开启数据标签控制图例位置、数据标签选项显示数值/类别名/系列名/图例项/百分比/气泡大小与网格线散点图按每两列构成一个系列的方式生成系列其余图表类型则按数据与类别引用自动构建默认图表尺寸为宽 15、高 7.5并通过OneCellAnchor将图表锚定到target_cell。数据透视表create_pivot_table( filepath: str, sheet_name: str, data_range: str, rows: List[str], values: List[str], columns: List[str] None, agg_func: str mean ) - strrows指定行标签字段values指定数值字段columns可选列标签字段agg_func聚合函数可选sum、count、average、max、min。需要提醒的是TOOLS.md 中的签名包含target_cell参数但当前 server.py 中的工具签名并不包含该参数。从 pivot.py 的实际实现看结果不会写入指定单元格而是自动新建名为源表名_pivot的工作表将透视结果以带样式的原生 Excel 表格形式写入其中。实现细节包括读取源数据后要求至少包含表头与一行数据自动清理字段名中的聚合后缀如sales (sum)→sales校验rows/values/columns字段是否真实存在于源数据表头中对行字段取值做笛卡尔组合逐组过滤并调用_aggregate_values完成聚合最终用TableStyleMedium9样式生成带斑马纹的 Excel 表格。Excel 原生表格create_table( filepath: str, sheet_name: str, data_range: str, table_name: str None, table_style: str TableStyleMedium9 ) - strdata_range形如A1:D5用于界定表格区域table_name不传时自动生成唯一名称Table_ 8 位随机十六进制table_style指定视觉样式默认TableStyleMedium9。对应实现在 tables.py会检查表名在defined_names中是否已存在避免重名冲突并默认开启行条纹showRowStripesTrue。区域操作与数据校验工具签名说明copy_rangecopy_range(filepath, sheet_name, source_start, source_end, target_start, target_sheetNone) - str复制单元格区域到新位置可跨工作表delete_rangedelete_range(filepath, sheet_name, start_cell, end_cell, shift_directionup) - str删除区域并平移剩余单元格shift_direction可选up或leftvalidate_excel_rangevalidate_excel_range(filepath, sheet_name, start_cell, end_cellNone) - str校验区域是否存在且格式合法get_data_validation_infoget_data_validation_info(filepath, sheet_name) - str获取工作表全部数据校验规则与元数据其中validate_excel_range的底层实现validation.py会返回非常丰富的诊断信息区域合法性、工作表实际数据范围A1:{最大列}{最大行}、目标区域是否超出数据边界extends_beyond_data以及数据维度等Agent 可以据此决定是否需要扩写或修正区域。get_data_validation_info返回的 JSON 中包含校验类型list、whole、decimal、date、time、textLength、运算符between、notBetween、equal、greaterThan、lessThan等、列表校验的允许值自动从引用区域解析、数值/日期校验的公式约束、校验生效的单元格范围以及提示与错误信息。此外read_data_from_excel会在单单元格层面自动附带这些校验元数据帮助 Agent 在写入前规避非法值。行列操作四个基于行/列号1 起始的结构化操作方便对工作表做增删调整工具签名说明insert_rowsinsert_rows(filepath, sheet_name, start_row, count1) - str从指定行开始插入 N 行insert_columnsinsert_columns(filepath, sheet_name, start_col, count1) - str从指定列开始插入 N 列delete_sheet_rowsdelete_sheet_rows(filepath, sheet_name, start_row, count1) - str从指定行开始删除 N 行delete_sheet_columnsdelete_sheet_columns(filepath, sheet_name, start_col, count1) - str从指定列开始删除 N 列源码中的工程细节错误处理、日志与协议约束深入源码可以发现这个服务在工程化上有几处值得借鉴的设计也是使用与二次开发时必须了解的约束。统一的错误分类exceptions.py 定义了面向业务域的异常体系ValidationError校验失败、WorkbookError工作簿级错误、SheetError工作表级错误、DataError数据读写错误、FormattingError格式化错误、CalculationError公式计算错误、PivotError透视表错误、ChartError图表错误。所有mcp.tool()方法都会捕获对应业务异常并返回以Error:开头的友好字符串同时记录日志对于未预期异常则抛出交由 MCP 框架处理。这种模式让 AI Agent 能直接从返回值中读取失败原因而不是面对晦涩的堆栈。日志必须写入文件而非 stdout在 stdio 模式下MCP 协议规定服务端 stdout 只能输出合法的 MCP 消息任何额外日志都会破坏协议帧。为此 server.py 将日志配置为仅使用FileHandler写入项目根目录下的excel-mcp.log文件并在注释中引用了 python-sdk 的 issue 说明这一约束。日志文件路径基于ROOT_DIR模块文件向上三级目录计算避免因客户端工作目录与权限差异导致日志文件创建失败。相对路径在 stdio 下的硬性限制get_excel_path()的路径策略绝对路径直通、相对路径仅限远程模式意味着本地 stdio 集成中调用任何工具时都应传递绝对路径否则会得到Invalid filename ... must be an absolute path when not in SSE mode的错误。这是本文强烈建议在 Agent 系统提示system prompt或工具封装层中预先约束的要点。实践建议与注意事项结合 README 说明与源码行为这里汇总几条实操要点本地使用优先 stdio在桌面 MCP 客户端中直接以uvx excel-mcp-server stdio启动文件路径由每次调用显式指定无需配置环境变量远程部署优先 streamable HTTPSSE 已被官方标记废弃新集成直接使用streamable-http并通过EXCEL_FILES_PATH限定服务端可访问的根目录、通过FASTMCP_PORT/FASTMCP_HOST控制监听端口与绑定地址注意默认端口源码默认端口为8017绑定0.0.0.0README 中的localhost:8000仅为示例请以实际端口为准配置客户端 URL善用校验工具写入前可先调用validate_excel_range、validate_formula_syntax、get_data_validation_info确认区域合法性与单元格约束read_data_from_excel返回的validation元数据也能帮助 Agent 理解什么值可以写透视表结果在独立工作表create_pivot_table会自动生成源表名_pivot工作表承载结果无需也无法指定目标单元格公式安全黑名单INDIRECT、HYPERLINK、WEBSERVICE、DGET、RTD等函数会被validate_formula拒绝涉及此类函数的公式将无法通过校验。进一步阅读完整工具文档TOOLS.md服务端工具注册与传输层实现server.pyCLI 入口与子命令定义main.py打包配置与依赖声明pyproject.toml数据读写与校验元数据实现data.py公式校验与区域校验实现validation.py图表与透视表实现chart.py、pivot.py【免费下载链接】klavisKlavis AI: MCP integration platforms that let AI agents use tools reliably at any scale项目地址: https://gitcode.com/GitHub_Trending/kl/klavis创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考 Excel MCP Server 实战指南：让 AI Agent 通过 MCP 协议直接创建、读取与修改 Excel 工作簿
Excel MCP Server 实战指南让 AI Agent 通过 MCP 协议直接创建、读取与修改 Excel 工作簿【免费下载链接】klavisKlavis AI: MCP integration platforms that let AI agents use tools reliably at any scale项目地址: https://gitcode.com/GitHub_Trending/kl/klavisExcel MCP Server 是 Klavis 开源仓库mcp_servers/local/excel目录下提供的一个 Model Context ProtocolMCP服务端实现它允许 AI Agent 在不安装 Microsoft Excel 的情况下完成工作簿创建、数据读写、公式应用、格式设置、图表与数据透视表生成等操作。本文以该目录的 README.md 为骨架结合 TOOLS.md 工具清单与src/excel_mcp源码实现完整讲解三种传输方式的配置、环境变量与文件路径处理、全部工具的能力与参数以及底层校验与错误处理机制帮助你在本地或远程环境中快速接入并可靠地使用这一 Excel 操作能力。项目定位与核心能力Excel MCP Server 是一个基于 Python 的 MCP 服务端底层使用openpyxl读写.xlsx文件通过FastMCP暴露工具接口。其核心设计目标是让 AI Agent 像操作本地 Excel 一样创建、读取、更新工作簿与工作表而无需安装微软 Office 套件。从 pyproject.toml 可以确认其技术栈与版本要求项值包名excel-mcp-server当前仓库版本 0.1.7Python 要求3.10核心依赖mcp[cli]1.10.1、fastmcp2.0.0,3.0.0、openpyxl3.1.5、typer0.16.0入口命令excel-mcp-server excel_mcp.__main__:app根据 README.md 的功能列表该服务覆盖以下能力域Excel 基础操作创建工作簿、工作表读取与更新数据数据处理公式、格式化、图表、数据透视表与 Excel 原生表格数据校验对区域range、公式与数据完整性提供内置校验格式化字体样式、颜色、边框、对齐与条件格式表格操作创建并管理带自定义样式的 Excel 表格图表创建折线图、柱状图、饼图、散点图、面积图等数据透视表面向数据分析的动态透视表生成工作表管理复制、重命名、删除工作表传输方式同时支持 stdio、SSE已标记废弃与 streamable HTTP 三种传输部署形态既可作为本地进程运行也可作为远程服务部署。快速开始三种传输方式的启动与配置服务提供了三个 Typer 子命令分别对应三种传输模式入口定义在main.pyuvx excel-mcp-server stdio # 本地 stdio 模式 uvx excel-mcp-server sse # SSE 模式已废弃 uvx excel-mcp-server streamable-http # 流式 HTTP 模式远程推荐1. Stdio 传输本地使用stdio 模式适合直接在本地 MCP 客户端如 Claude Desktop、Cursor 等中通过子进程方式启动。服务端与客户端之间通过标准输入/输出进行 MCP 消息通信因此该模式下服务端不能向 stdout 写入任何非 MCP 协议的日志详见下文日志与协议约束。{ mcpServers: { excel: { command: uvx, args: [excel-mcp-server, stdio] } } }2. SSE 传输已废弃SSEServer-Sent Events传输曾在远程场景中广泛使用README 已明确标注其Deprecated已废弃状态新项目建议直接采用 streamable HTTP。若仍需连接旧服务可这样配置{ mcpServers: { excel: { url: http://localhost:8000/sse } } }3. Streamable HTTP 传输远程连接推荐streamable HTTP 是当前 MCP 标准推荐的远程传输方式服务端监听 HTTP 端口并提供/mcp端点{ mcpServers: { excel: { url: http://localhost:8000/mcp } } }需要特别指出的是上述两个 JSON 示例中的端口8000是 README 中的示例值。从 server.py 的实际实现看FastMCP初始化时端口的默认值是8017mcp FastMCP( excel-mcp, hostos.environ.get(FASTMCP_HOST, 0.0.0.0), portint(os.environ.get(FASTMCP_PORT, 8017)), instructionsExcel MCP Server for manipulating Excel files )因此如果未显式设置FASTMCP_PORT客户端应连接http://host:8017/mcp或http://host:8017/sse。环境变量与文件路径处理这是使用该服务时最容易踩坑的部分README 与源码在路径语义上给出了明确区分。远程模式SSE / Streamable HTTP下的 EXCEL_FILES_PATH当以 SSE 或 streamable HTTP 协议运行时服务端必须设置EXCEL_FILES_PATH环境变量用于告知服务端从哪里读取、向哪里写入 Excel 文件如果未设置则默认使用./excel_files。对应实现位于 server.py 的run_sse()与run_streamable_http()两者都会读取该环境变量并自动创建目录EXCEL_FILES_PATH os.environ.get(EXCEL_FILES_PATH, ./excel_files) os.makedirs(EXCEL_FILES_PATH, exist_okTrue)同时可通过FASTMCP_PORT控制监听端口未设置时默认8017。此外从源码还可以看到服务端还支持FASTMCP_HOST环境变量默认绑定0.0.0.0方便远程访问。Windows PowerShell 示例$env:EXCEL_FILES_PATHE:\MyExcelFiles $env:FASTMCP_PORT8007 uvx excel-mcp-server streamable-httpLinux/macOS 示例EXCEL_FILES_PATH/path/to/excel_files FASTMCP_PORT8007 uvx excel-mcp-server streamable-httpStdio 模式下的路径语义与远程模式不同stdio 模式下无需在服务端设置EXCEL_FILES_PATH每次工具调用时由客户端直接传入文件路径服务端按调用中的路径执行操作。这一设计在源码中有完整的体现。server.py中的get_excel_path()函数负责路径解析server.py如果传入的是绝对路径直接返回该路径如果传入的是相对路径且EXCEL_FILES_PATH为None即 stdio 模式会抛出ValueError提示必须使用绝对路径如果传入相对路径且处于远程模式则基于EXCEL_FILES_PATH拼接出完整路径。这套逻辑意味着在本地 stdio 集成中AI Agent 对文件位置拥有完全的控制权而在远程部署中所有文件操作都被限制在服务端指定的根目录内便于统一管理与权限收敛。工具全景从工作簿到单元格的完整操作矩阵完整的工具清单与签名记录在 TOOLS.md 中而 server.py 中的mcp.tool()装饰器对应着每个工具的运行时注册。以下按功能域逐一展开。工作簿与工作表操作工具签名说明create_workbookcreate_workbook(filepath: str) - str新建 Excel 工作簿返回创建成功的文件路径create_worksheetcreate_worksheet(filepath, sheet_name) - str在已有工作簿中新建工作表get_workbook_metadataget_workbook_metadata(filepath, include_ranges: bool False) - str获取工作簿元数据include_rangesTrue时附带各工作表已使用区域如A1:D20copy_worksheetcopy_worksheet(filepath, source_sheet, target_sheet) - str在工作簿内复制工作表delete_worksheetdelete_worksheet(filepath, sheet_name) - str删除工作表rename_worksheetrename_worksheet(filepath, old_name, new_name) - str重命名工作表在源码层面create_workbook的实现位于 workbook.py它创建openpyxl.Workbook实例、将默认的Sheet重命名为Sheet1并在保存前自动创建父目录path.parent.mkdir(parentsTrue, exist_okTrue)。get_workbook_info则返回文件名、工作表列表、文件大小与修改时间并可按需计算每个工作表的使用范围A1:{最大列字母}{最大行号}。数据读写写入数据write_data_to_excel( filepath: str, sheet_name: str, data: List[Dict], start_cell: str A1 ) - strdata为要写入的数据TOOLS.md 描述为字典列表源码中实际按行处理的二维列表start_cell指定写入起始单元格默认A1。从 data.py 的实现看write_data对 sheet 名称做了智能处理未指定时写入活动工作表指定的表不存在时会自动创建随后通过parse_cell_range校验起始单元格格式再逐行逐列写入并保存。读取数据read_data_from_excel( filepath: str, sheet_name: str, start_cell: str A1, end_cell: str None, preview_only: bool False ) - strend_cell可选不传时自动扩展到工作表的数据边界返回值为 JSON 字符串包含区域信息、工作表名以及每个单元格的地址、值、行号、列号。值得关注的是读取能力的深度read_excel_range_with_metadatadata.py会在读取时为每个单元格附带校验元数据validation字段即当单元格存在数据校验规则时一并返回没有校验时返回{has_validation: False}。这意味着 AI Agent 在写入前就能感知目标单元格的约束条件。格式化与合并format_range是参数最丰富的工具之一format_range( filepath: str, sheet_name: str, start_cell: str, end_cell: str None, bold: bool False, italic: bool False, underline: bool False, font_size: int None, font_color: str None, bg_color: str None, border_style: str None, border_color: str None, number_format: str None, alignment: str None, wrap_text: bool False, merge_cells: bool False, protection: Dict[str, Any] None, conditional_format: Dict[str, Any] None ) - str它覆盖了字体加粗/斜体/下划线/字号/颜色、背景色、边框样式与颜色、数字格式、对齐方式、自动换行、合并单元格、单元格保护与条件格式等能力。其底层实现在 formatting.py 中由server.py的format_range工具转发调用。合并相关的三个独立工具工具签名说明merge_cellsmerge_cells(filepath, sheet_name, start_cell, end_cell) - str合并单元格区域unmerge_cellsunmerge_cells(filepath, sheet_name, start_cell, end_cell) - str取消合并get_merged_cellsget_merged_cells(filepath, sheet_name) - str获取工作表内已合并的区域公式操作工具签名说明apply_formulaapply_formula(filepath, sheet_name, cell, formula) - str向单元格写入公式带校验validate_formula_syntaxvalidate_formula_syntax(filepath, sheet_name, cell, formula) - str仅校验公式语法不写入apply_formula的执行链路在源码中非常清晰calculations.py先校验单元格引用是否合法再确保公式以开头随后调用validate_formula做语法与安全性检查通过后写入并保存。而 validation.py 中的validate_formula实现了两层校验语法层公式必须以开头括号必须配对不允许未闭合或多余的右括号安全层通过正则提取函数名黑名单拦截INDIRECT、HYPERLINK、WEBSERVICE、DGET、RTD等易被用于注入或外联的危险函数。此外validate_formula_in_cell_operation即validate_formula_syntax与apply_formula共用的底层校验还会解析公式中引用的单元格/区域并对比单元格现有内容返回valid、matches、current_formula等详细信息供 Agent 判断公式是否已与单元格内容一致。图表创建create_chart( filepath: str, sheet_name: str, data_range: str, chart_type: str, target_cell: str, title: str , x_axis: str , y_axis: str ) - strchart_type支持line折线、bar柱状、pie饼图、scatter散点、area面积data_range为图表数据来源区域target_cell指定图表锚定位置。图表底层实现在 chart.py 中源码揭示了比工具签名更丰富的细节支持通过SheetName!A1:B2语法跨工作表引用数据区域支持style字典内部默认开启数据标签控制图例位置、数据标签选项显示数值/类别名/系列名/图例项/百分比/气泡大小与网格线散点图按每两列构成一个系列的方式生成系列其余图表类型则按数据与类别引用自动构建默认图表尺寸为宽 15、高 7.5并通过OneCellAnchor将图表锚定到target_cell。数据透视表create_pivot_table( filepath: str, sheet_name: str, data_range: str, rows: List[str], values: List[str], columns: List[str] None, agg_func: str mean ) - strrows指定行标签字段values指定数值字段columns可选列标签字段agg_func聚合函数可选sum、count、average、max、min。需要提醒的是TOOLS.md 中的签名包含target_cell参数但当前 server.py 中的工具签名并不包含该参数。从 pivot.py 的实际实现看结果不会写入指定单元格而是自动新建名为源表名_pivot的工作表将透视结果以带样式的原生 Excel 表格形式写入其中。实现细节包括读取源数据后要求至少包含表头与一行数据自动清理字段名中的聚合后缀如sales (sum)→sales校验rows/values/columns字段是否真实存在于源数据表头中对行字段取值做笛卡尔组合逐组过滤并调用_aggregate_values完成聚合最终用TableStyleMedium9样式生成带斑马纹的 Excel 表格。Excel 原生表格create_table( filepath: str, sheet_name: str, data_range: str, table_name: str None, table_style: str TableStyleMedium9 ) - strdata_range形如A1:D5用于界定表格区域table_name不传时自动生成唯一名称Table_ 8 位随机十六进制table_style指定视觉样式默认TableStyleMedium9。对应实现在 tables.py会检查表名在defined_names中是否已存在避免重名冲突并默认开启行条纹showRowStripesTrue。区域操作与数据校验工具签名说明copy_rangecopy_range(filepath, sheet_name, source_start, source_end, target_start, target_sheetNone) - str复制单元格区域到新位置可跨工作表delete_rangedelete_range(filepath, sheet_name, start_cell, end_cell, shift_directionup) - str删除区域并平移剩余单元格shift_direction可选up或leftvalidate_excel_rangevalidate_excel_range(filepath, sheet_name, start_cell, end_cellNone) - str校验区域是否存在且格式合法get_data_validation_infoget_data_validation_info(filepath, sheet_name) - str获取工作表全部数据校验规则与元数据其中validate_excel_range的底层实现validation.py会返回非常丰富的诊断信息区域合法性、工作表实际数据范围A1:{最大列}{最大行}、目标区域是否超出数据边界extends_beyond_data以及数据维度等Agent 可以据此决定是否需要扩写或修正区域。get_data_validation_info返回的 JSON 中包含校验类型list、whole、decimal、date、time、textLength、运算符between、notBetween、equal、greaterThan、lessThan等、列表校验的允许值自动从引用区域解析、数值/日期校验的公式约束、校验生效的单元格范围以及提示与错误信息。此外read_data_from_excel会在单单元格层面自动附带这些校验元数据帮助 Agent 在写入前规避非法值。行列操作四个基于行/列号1 起始的结构化操作方便对工作表做增删调整工具签名说明insert_rowsinsert_rows(filepath, sheet_name, start_row, count1) - str从指定行开始插入 N 行insert_columnsinsert_columns(filepath, sheet_name, start_col, count1) - str从指定列开始插入 N 列delete_sheet_rowsdelete_sheet_rows(filepath, sheet_name, start_row, count1) - str从指定行开始删除 N 行delete_sheet_columnsdelete_sheet_columns(filepath, sheet_name, start_col, count1) - str从指定列开始删除 N 列源码中的工程细节错误处理、日志与协议约束深入源码可以发现这个服务在工程化上有几处值得借鉴的设计也是使用与二次开发时必须了解的约束。统一的错误分类exceptions.py 定义了面向业务域的异常体系ValidationError校验失败、WorkbookError工作簿级错误、SheetError工作表级错误、DataError数据读写错误、FormattingError格式化错误、CalculationError公式计算错误、PivotError透视表错误、ChartError图表错误。所有mcp.tool()方法都会捕获对应业务异常并返回以Error:开头的友好字符串同时记录日志对于未预期异常则抛出交由 MCP 框架处理。这种模式让 AI Agent 能直接从返回值中读取失败原因而不是面对晦涩的堆栈。日志必须写入文件而非 stdout在 stdio 模式下MCP 协议规定服务端 stdout 只能输出合法的 MCP 消息任何额外日志都会破坏协议帧。为此 server.py 将日志配置为仅使用FileHandler写入项目根目录下的excel-mcp.log文件并在注释中引用了 python-sdk 的 issue 说明这一约束。日志文件路径基于ROOT_DIR模块文件向上三级目录计算避免因客户端工作目录与权限差异导致日志文件创建失败。相对路径在 stdio 下的硬性限制get_excel_path()的路径策略绝对路径直通、相对路径仅限远程模式意味着本地 stdio 集成中调用任何工具时都应传递绝对路径否则会得到Invalid filename ... must be an absolute path when not in SSE mode的错误。这是本文强烈建议在 Agent 系统提示system prompt或工具封装层中预先约束的要点。实践建议与注意事项结合 README 说明与源码行为这里汇总几条实操要点本地使用优先 stdio在桌面 MCP 客户端中直接以uvx excel-mcp-server stdio启动文件路径由每次调用显式指定无需配置环境变量远程部署优先 streamable HTTPSSE 已被官方标记废弃新集成直接使用streamable-http并通过EXCEL_FILES_PATH限定服务端可访问的根目录、通过FASTMCP_PORT/FASTMCP_HOST控制监听端口与绑定地址注意默认端口源码默认端口为8017绑定0.0.0.0README 中的localhost:8000仅为示例请以实际端口为准配置客户端 URL善用校验工具写入前可先调用validate_excel_range、validate_formula_syntax、get_data_validation_info确认区域合法性与单元格约束read_data_from_excel返回的validation元数据也能帮助 Agent 理解什么值可以写透视表结果在独立工作表create_pivot_table会自动生成源表名_pivot工作表承载结果无需也无法指定目标单元格公式安全黑名单INDIRECT、HYPERLINK、WEBSERVICE、DGET、RTD等函数会被validate_formula拒绝涉及此类函数的公式将无法通过校验。进一步阅读完整工具文档TOOLS.md服务端工具注册与传输层实现server.pyCLI 入口与子命令定义main.py打包配置与依赖声明pyproject.toml数据读写与校验元数据实现data.py公式校验与区域校验实现validation.py图表与透视表实现chart.py、pivot.py【免费下载链接】klavisKlavis AI: MCP integration platforms that let AI agents use tools reliably at any scale项目地址: https://gitcode.com/GitHub_Trending/kl/klavis创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考