Excel MCP Server

# 常见问题 (FAQ) ## 🚀 安装和配置 ### Q: 如何检查Python版本是否满足要求？ A: 运行以下命令检查Python版本： ```bash python --version # 或 python3 --version ``` 需要Python 3.10或更高版本。 ### Q: 安装依赖时出现错误怎么办？ A: 尝试以下解决方案： 1. 升级pip：`pip install --upgrade pip` 2. 使用虚拟环境： ```bash python -m venv excel_mcp_env source excel_mcp_env/bin/activate # Linux/Mac # 或 excel_mcp_env\Scripts\activate # Windows pip install -r requirements.txt ``` 3. 如果某些包安装失败，可以跳过可选依赖继续使用 ### Q: Claude Desktop配置文件在哪里？ A: 根据操作系统： - **macOS**: `~/Library/Application Support/Claude/claude_desktop_config.json` - **Windows**: `%APPDATA%\Claude\claude_desktop_config.json` - **Linux**: `~/.config/Claude/claude_desktop_config.json` ## 🔧 使用问题 ### Q: 服务器启动后没有响应？ A: 检查以下几点： 1. 确保所有依赖正确安装 2. 检查配置文件路径是否正确 3. 查看日志文件：`logs/excel_mcp.log` 4. 尝试重新启动Claude Desktop ### Q: 无法读取Excel文件？ A: 可能的原因： 1. **文件路径错误**: 确保文件路径正确且文件存在 2. **权限问题**: 检查是否有读取文件的权限 3. **文件不在允许的路径**: 检查`config.json`中的`allowed_paths`配置 4. **文件格式不支持**: 确保文件是.xlsx、.xls或.csv格式 ### Q: 写入Excel文件失败？ A: 检查以下几点： 1. **写入权限**: 确保有写入目录的权限 2. **文件被占用**: 关闭Excel或其他程序中打开的同名文件 3. **路径权限**: 确保目标路径在`allowed_paths`配置中 4. **磁盘空间**: 检查是否有足够的磁盘空间 ### Q: 如何查看详细的错误信息？ A: 查看日志文件： ```bash tail -f logs/excel_mcp.log ``` 或者运行测试来诊断问题： ```bash python test_quick.py ``` ## 🛡️ 安全问题 ### Q: 如何设置允许访问的目录？ A: 编辑`config.json`文件中的`security.allowed_paths`： ```json { "security": { "allowed_paths": [ "./data", "~/Documents", "~/Desktop", "/path/to/your/excel/files" ] } } ``` ### Q: 如何限制文件大小？ A: 在`config.json`中修改`excel.max_file_size`： ```json { "excel": { "max_file_size": "100MB" } } ``` ### Q: 备份文件存储在哪里？ A: 备份文件默认存储在`temp/`目录中，文件名包含时间戳。可以通过`config.json`中的`excel.temp_dir`修改备份目录。 ## 📊 功能使用 ### Q: 支持哪些Excel格式？ A: 目前支持： - `.xlsx` - Excel 2007+格式（推荐） - `.xls` - Excel 97-2003格式 - `.csv` - 逗号分隔值文件 ### Q: 如何使用公式功能？ A: 在Claude中使用自然语言描述： ``` 在单元格D2中应用公式 =B2*C2 来计算总价 ``` 公式会自动添加等号前缀（如果没有的话）。 ### Q: 可以处理多大的Excel文件？ A: 默认限制为100MB，可以通过配置文件调整。实际处理能力取决于： - 系统内存 - Python环境 - pandas和openpyxl的性能限制 ### Q: 如何查询特定条件的数据？ A: 使用自然语言描述查询条件： ``` 查找销售额大于1000的所有记录 查找部门为"销售"的员工 查找价格在10到50之间的产品 ``` ## 🔄 故障排除 ### Q: Claude Desktop中看不到Excel功能？ A: 检查步骤： 1. 确认配置文件路径正确 2. 重启Claude Desktop应用 3. 检查服务器是否正常启动 4. 查看Claude Desktop的日志 ### Q: 服务器突然停止工作？ A: 可能的解决方案： 1. 检查日志文件查看错误信息 2. 重启服务器：`python server.py` 3. 检查系统资源（内存、磁盘空间） 4. 重新安装依赖 ### Q: 性能问题怎么优化？ A: 优化建议： 1. 避免处理过大的Excel文件 2. 使用指定范围读取而不是读取整个文件 3. 定期清理临时文件和备份 4. 关闭不必要的其他应用程序 ## 📝 开发相关 ### Q: 如何添加新的MCP工具？ A: 在`src/excel_mcp/server.py`中： 1. 使用`@mcp.tool()`装饰器 2. 定义函数参数和返回类型 3. 实现具体功能 4. 添加相应的测试用例 ### Q: 如何扩展支持的文件格式？ A: 需要修改： 1. `config.json`中的`supported_formats` 2. `file_manager.py`中的文件处理逻辑 3. 添加相应的库依赖 ### Q: 如何贡献代码？ A: 请查看 [贡献指南](CONTRIBUTING.md) 了解详细流程。 ## 🆘 获取更多帮助 如果这里没有解决你的问题： 1. 查看 [项目文档](docs/) 2. 搜索 [GitHub Issues](https://github.com/YOUR_USERNAME/excel-mcp/issues) 3. 创建新的 [Issue](https://github.com/YOUR_USERNAME/excel-mcp/issues/new) 4. 参与 [Discussions](https://github.com/YOUR_USERNAME/excel-mcp/discussions)