Excel表格管理服务

Excel MCP服务器

一个与FastMCP兼容的服务器，允许助手检查、编辑和配置Excel工作簿。该服务公开了由以下支持的结构化MCP工具 openpyxl，提供了一个可选的FastAPI UI用于文件管理，并打包部署在具有持久存储的Fly.io上。

项目结构

• MCPserver.py 定义配置日志记录和Excel工作区路径的FastMCP服务器、工具注册表、中间件和启动/关闭挂钩。
• FASTAPIserver.py 将MCP服务器封装在FastAPI中，提供可选 webapp/ 资产，并添加用于上传、列出、下载和删除电子表格的REST助手。
• run_server.py 收集环境变量，并启动组合的FastAPI/MCP堆栈 uvicorn.
• src/
  • data.py, sheet.py, workbook.py 实现为MCP工具供电的读/写操作。
  • cell_utils.py 解析A1样式范围，以便工具能够可靠地解析坐标。
  • exceptions.py 和 Outputclasses.py 集中错误类型和返回给客户端的结构化响应。
• webapp/ 包含Vite构建的静态UI。当 webapp/assets 存在，它与MCP API一起提供服务。
• data/ 是在Fly.io上运行时Excel文件的默认可写目录。
• fly.toml 配置Fly.io应用程序、HTTP服务和持久卷装载。

运行时与uv的依赖关系

此项目使用 紫外线 管理中声明的Python环境 pyproject.toml:

• anyio 提供FastAPI和FastMCP使用的结构化并发原语。
• fastapi 承载HTTP端点，并将MCP服务器桥接到web。
• fastmcp 提供模型上下文协议服务器运行时、工具装饰器和中间件挂钩。
• mcp[cli] 捆绑了CLI工具，使在本地测试MCP调用变得容易。
• openpyxl 读取和写入MCP工具引用的Excel工作簿。
• vite 构建在以下位置提供的可选web UI / 当资产存在时。

安装uv（一次）和同步依赖项：

curl -LsSf https://astral.sh/uv/install.sh | sh  # follow official instructions for your platform
uv sync

uv sync 解析锁文件，创建虚拟环境，并在一个步骤中安装上述软件包。

地方发展

1. 确保紫外线已安装并运行 uv sync.
2. 为Excel文件选择一个目录并导出：
   复制

   export EXCEL_FILES_PATH=./excel_files
   mkdir -p "$EXCEL_FILES_PATH"
   

3. （可选）选择日志目标：
   复制

   export LOG_FILE_PATH=./logs
   mkdir -p "$LOG_FILE_PATH"
   

4. 启动服务器：
   复制

   uv run python run_server.py
   

5. FastAPI应用程序正在监听 0.0.0.0:8000.打开 / 加载UI（如果已构建）或将MCP客户端连接到 /mcp.
6. 对运输工具进行卫生检查：
   复制

   uv run mcp ping http://127.0.0.1:8000/mcp
   

部署到Fly.io

1. 安装Fly.io CLI并进行身份验证： fly auth login.
2. 创建应用程序（一次）： fly launch --no-deploy 保持生成 fly.toml.
3. 提供中引用的持久卷 fly.toml:
   复制

   fly volumes create myapp_data --size 1
   

4. 部署：
   复制

   fly deploy
   

5. 验证机器和日志： fly status 和 fly logs.

Fly配置暴露端口 8000，安装 /app/data，并保持一台机器在线，以便MCP客户端可以立即连接。调整CPU、内存或缩放比例 fly.toml 以适应你的工作量。

制作笔记

• 限制对受信任客户端的访问，或将服务置于经过身份验证的代理之后；该工具集可以修改电子表格。
• 验证为上传/删除端点提供的文件名，以避免路径遍历。
• 监视器 excel-mcp.log 和 excel-mcp-error.log，根据需要旋转或导出日志。