AI导哈

Excel文件操作服务器

一个用于Excel文件操作和工程计算分析的Python服务器，支持跨平台使用。

  • by goldsmith323
  • Python
  • 本地部署
  • 更新于
在 GitHub 查看 goldsmith323/excel-mcp

使用说明

Excel MCP服务器

使用Python进行Excel文件操作和工程计算器分析的模型上下文协议（MCP）服务器。

作者 侯赛因·扎尔加

特性

  • get_document_info：获取有关Excel文档的基本信息，包括工作表名称、尺寸和元数据
  • update_cell：使用A1表示法更新单元格值（例如“A1”、“B5”）
  • 高级工程分析：通过参数检测和公式分析分析工程计算器
  • 跨平台：适用于Windows、macOS和Linux
  • 示例文件：包括用于测试的示例Excel文件

安装

  1. 安装依赖项：
pip install -r requirements.txt
  1. 运行服务器：

在Linux/macOS上：

python3 -m src.excel_mcp.simple_server

在Windows上：

python -m src.excel_mcp.simple_server

快速开始

存储库包括用于测试的示例Excel文件。要快速开始：

在Linux/macOS上：

./start_simple_monitor.sh

在Windows上：

start_simple_monitor.bat

用法

设置 EXCEL_FILE_PATH 用于指定Excel文件的环境变量：

在Linux/macOS上：

EXCEL_FILE_PATH=/path/to/your/file.xlsx python3 -m src.excel_mcp.simple_server

在Windows上：

set EXCEL_FILE_PATH=path\to\your\file.xlsx
python -m src.excel_mcp.simple_server

项目结构

excel-mcp/
├── src/excel_mcp/
│   ├── simple_server.py         # Main MCP server with engineering tools
│   ├── engineering_tools.py     # Advanced engineering analysis
│   ├── excel_tools.py          # Basic Excel operations
│   └── __init__.py             # Python package marker
├── excel_files/                # Sample Excel files for testing
├── excel_monitor_simple.py     # Desktop monitor application
├── start_simple_monitor.sh     # Launcher script (Linux/macOS)
├── start_simple_monitor.bat    # Launcher script (Windows)
└── README.md                   # Project documentation

运作原理

  1. Excel监视器 (excel_monitor_simple.py)检测打开Excel文件的时间
  2. 用户选择 将文件连接到MCP桌面客户端
  3. MCP服务器 (simple_server.py)已配置并启动
  4. MCP桌面客户端 连接到MCP服务器
  5. 系统分析 使用工程工具的Excel文件

MCP工具

Excel基本操作

get_document_info

返回有关Excel文件的信息，包括：

  • 文件路径和大小
  • 张数
  • 图纸名称和尺寸

update_cell

更新指定工作表中的单元格值。

参数：

  • sheet_name：工作表名称
  • cell_address：A1表示法中的单元格地址（例如“A1”、“B5”）
  • value：单元格的新值

工程分析工具

分析工程计算器

对工程计算器进行全面分析，包括：

  • 计算器类型标识
  • 输入/输出参数检测
  • 公式复杂性分析
  • 单位和验证规则

find_input_parameters

在工程计算器中定位和分析输入参数。

get_calculator_summary

提供计算器功能和工程领域的高级摘要。

开发指南

添加新的MCP工具

位置: src/excel_mcp/simple_server.py

  1. 添加工具定义 在……里面 handle_list_tools():
types.Tool(
    name="your_new_tool",
    description="What your tool does",
    inputSchema={
        "type": "object",
        "properties": {
            "param_name": {
                "type": "string",
                "description": "Parameter description"
            }
        },
        "required": ["param_name"]
    }
)
  1. 添加工具处理程序 在……里面 handle_call_tool():
elif name == "your_new_tool":
    param_value = arguments.get("param_name")
    
    # Your tool logic here
    result = do_something(param_value)
    
    return [types.TextContent(
        type="text",
        text=f"Result: {result}"
    )]

扩展工程分析

位置: src/excel_mcp/engineering_tools.py

这 EngineeringExcelAnalyzer 类包含以下方法：

  • _identify_calculator_type() -确定计算器用途
  • _find_input_parameters() -查找输入字段
  • _analyze_formulas() -检查Excel公式
  • _analyze_units() -检查单位和换算

要添加新的分析，请执行以下操作：

  1. 添加方法 EngineeringExcelAnalyzer 类
  2. 打电话给 analyze_calculator_structure()
  3. 在中添加相应的MCP工具 simple_server.py

支持新文件类型

目前支持： .xlsx, .xls, .xlsm, .xlsb

要添加新类型，请执行以下操作：

  1. 更新中的文件扩展名 get_open_excel_files()
  2. 确保 openpyxl 或添加新库可以读取格式
  3. 使用示例文件进行测试

测试

1.直接测试MCP服务器

在Linux/macOS上：

cd excel-mcp
EXCEL_FILE_PATH="/path/to/test.xlsx" python3 src/excel_mcp/simple_server.py

在Windows上：

cd excel-mcp
set EXCEL_FILE_PATH=excel_files\beam_analysis.xlsx
python src/excel_mcp/simple_server.py

2.使用Excel Monitor进行测试

在Linux/macOS上：

cd excel-mcp
./start_simple_monitor.sh

在Windows上：

cd excel-mcp
start_simple_monitor.bat

然后打开一个Excel文件，并在提示时选择连接。

3.使用MCP客户端进行测试

  1. 使用监视器连接文件
  2. 打开您的MCP客户端
  3. 尝试以下命令：
    • “分析此工程计算器”
    • “显示输入参数”
    • “使用了哪些公式？”

关键库

MCP（模型上下文协议）

  • 目的：MCP客户端和服务器之间的通信
  • 文档: https://modelcontextprotocol.io/
  • 关键概念：工具、资源、提示

OpenPyXL

  • 目的：读取/写入Excel文件
  • 文档: https://openpyxl.readthedocs.io/
  • 主要特点：单元格访问、公式、格式

psutil

  • 目的：系统和过程监控
  • 文档: https://psutil.readthedocs.io/
  • 用例：检测正在运行的Excel进程

常见开发任务

添加对新工程领域的支持

  1. 更新域检测 在……里面 _identify_calculator_type():
elif any(word in sheet_text for word in ['your', 'domain', 'keywords']):
    calculator_info['engineering_domain'] = 'Your Engineering Domain'
  1. 添加特定于域的模式 在……里面 engineering_keywords:
'your_domain': ['keyword1', 'keyword2', 'keyword3']

改进参数检测

  1. 添加新的参数模式 在……里面 engineering_keywords
  2. 增强 _analyze_parameter_cell() 查看更多位置
  3. 更新单位模式 在……里面 unit_patterns

添加公式验证

  1. 创建新方法 在……里面 EngineeringExcelAnalyzer:
def _validate_formulas(self) -> List[Dict[str, Any]]:
    # Your validation logic
    pass
  1. 添加MCP工具 用于公式验证
  2. 使用工程计算器进行测试

调试提示

MCP服务器问题

  • 检查启动监视器的终端中的错误消息
  • 验证 EXCEL_FILE_PATH 环境变量设置正确
  • 使用手动环境变量直接测试MCP服务器

Excel检测问题

  • 检查Excel进程名称是否与您的系统匹配
  • 验证检测逻辑中是否包含文件扩展名
  • 测试 get_open_excel_files() 独立方法

MCP客户端连接问题

  • 检查配置是否正确更新
  • 配置更改后重新启动MCP客户端
  • 验证文件路径是否绝对正确

代码风格指南

  • 使用描述性变量名 工程概念
  • 添加文档字符串 所有公共方法
  • 优雅地处理错误 使用try/catch块
  • 一致地格式化结果 MCP客户端响应
  • 添加类型提示 在可能的情况下

需求

  • Python 3.8+
  • openpyxl>=3.1.0
  • p值>=5.9.0
  • mcp>=1.0.0
  • 熊猫>=2.0.0
  • 数值>=1.24.0

许可证

MIT许可证-有关详细信息，请参阅许可证文件。

学习资源

  • MCP协议: https://modelcontextprotocol.io/docs/
  • Excel文件格式：OpenPyXL文档
  • 工程标准：UFC、AISC、ACI文件
  • Python开发：Python.org教程

该系统为Excel MCP集成提供了坚实的基础，并为广泛的定制和增强提供了空间。

相关 MCP