LLM Excel MCP Server

LLM驱动的Excel自动化MCP服务器

生产型个人项目，通过MCP（模型上下文协议）服务器和FastAPI HTTP API向LLM公开Excel自动化功能。该系统允许LLM安全地加载、清理、配置和转换Excel工作簿——无论是在本地还是部署在Render的自由层上。

______________________________________________________________________

1.问题陈述

大多数“LLM+电子表格”演示依赖于脆弱的CSV解析或临时脚本。很少有：

• 确定性、可审计的工具层 在LLM和Excel之间。
• 清除服务器边界 适合在Render等平台上部署。
• 支持投资组合的后端 招聘人员可以快速理解和运行。

该项目通过提供 类型化、结构良好的Excel MCP服务器 LLM可以通过工具调用，同时也可以公开相同的操作 FastAPI端点.

______________________________________________________________________

2.高层架构

文本图表：

• 用户

- 交谈→

• 当地LLM（Ollama-Calma 3/PHI-3）

- 决定调用哪些MCP工具→

• MCP服务器（Python MCP SDK）

- 代表们工作→

• Excel操作层（pandas+openpyxl）

- 读/写→

• Excel文件（位于 sample_files/)

- 回复返回到→

• LLM/用户

同时，相同的操作也暴露在 HTTP端点 使用 快速API，因此您可以使用进行测试 邮差/卷发 并部署到 渲染.

______________________________________________________________________

3.特点

• Excel加载和清理

- 从以下位置加载特定纸张 .xlsx 文件夹。 - 删除空行，规范列名，并推断数据类型。

• 数据探查

- 行/列计数。 - 列列表。 - 每列空计数。

• 数据透视表创建

- 灵活的 index, values，以及 aggfunc (sum, mean, count). - 以JSON格式返回旋转数据，供LLM使用。

• 公式插入

- 使用以下命令将任意Excel公式插入特定单元格 openpyxl.

• LLM的MCP工具

- clean_excel - profile_excel - create_pivot_table - insert_excel_formula

• FastAPI HTTP端点

- /health - /mcp/clean-excel - /mcp/profile-excel - /mcp/create-pivot-table - /mcp/insert-formula

• 本地LLM演示客户端

- 调用的最小助手 奥拉玛 并引导模型发出JSON工具调用。

• Docker化和渲染就绪

- python:3.10-slim 基地。 - 暴露端口 10000.

______________________________________________________________________

4.技术栈

• 语言：Python 3.10+
• API框架：FastAPI
• Excel操作：pandas，openpyxl
• MCP服务器: mcp （Python MCP SDK）
• 本地法学硕士：Ollama（火焰3/PHI-3）
• 可选云LLM：Groq（仅限免费层，非硬编码）
• 部署：免费渲染层上的Docker
• 演示客户端：HTTP（Postman/cill），本地LLM演示助手

______________________________________________________________________

5.存储库结构

llm-excel-mcp-server/

├── app/
│   ├── main.py          # FastAPI app entry point
│   ├── mcp_server.py    # MCP tool definitions
│   ├── excel_ops.py     # Excel operation logic
│   ├── schemas.py       # Pydantic request/response models
│   ├── config.py        # App configuration
│   ├── utils.py         # Helper utilities
│   └── llm_client.py    # Local LLM helper for demos (Ollama)
│
├── sample_files/
│   ├── .gitkeep
│   └── sales_data.xlsx  # (created locally by you – not committed)
│
├── tests/
│   └── __init__.py
│
├── Dockerfile
├── requirements.txt
├── README.md
└── .gitignore

______________________________________________________________________

6.本地设置

6.1先决条件

• python 3.10+
• pip
• （LLM流量可选） 奥拉玛 本地安装：

- 从以下位置安装 https://ollama.com - 然后运行：

ollama pull llama3

6.2创建并激活virtualenv

cd llm-excel-mcp-server
python -m venv .venv
source .venv/bin/activate        # Linux / macOS
# or
.venv\Scripts\activate           # Windows

6.3安装依赖项

pip install --upgrade pip
pip install -r requirements.txt

6.4创建示例Excel文件

在 sample_files/，创建名为的工作簿 sales_data.xlsx 用床单 Sales 包含以下列：

• Region
• Product
• Revenue
• Quantity

最小数据示例：

另存为 sample_files/sales_data.xlsx.

______________________________________________________________________

7.在本地运行服务器

使用uvicorn启动FastAPI应用程序：

uvicorn app.main:app --reload

默认情况下，应用程序在 http://127.0.0.1:8000。Render部署将侦听端口 10000 在容器内。

• 健康检查: GET /health
• OpenAPI文档: GET /docs

______________________________________________________________________

8.HTTP端点和示例调用

所有示例都假设服务器在本地运行 http://127.0.0.1:8000.

• 清理Excel

curl -X POST http://127.0.0.1:8000/mcp/clean-excel \
  -H "Content-Type: application/json" \
  -d '{
    "path": "sales_data.xlsx",
    "sheet": "Sales"
  }'

• 配置文件Excel

curl -X POST http://127.0.0.1:8000/mcp/profile-excel \
  -H "Content-Type: application/json" \
  -d '{
    "path": "sales_data.xlsx",
    "sheet": "Sales"
  }'

• 创建数据透视表

curl -X POST http://127.0.0.1:8000/mcp/create-pivot-table \
  -H "Content-Type: application/json" \
  -d '{
    "path": "sales_data.xlsx",
    "sheet": "Sales",
    "index": ["Region"],
    "values": ["Revenue"],
    "aggfunc": "sum"
  }'

• 插入公式

curl -X POST http://127.0.0.1:8000/mcp/insert-formula \
  -H "Content-Type: application/json" \
  -d '{
    "path": "sales_data.xlsx",
    "sheet": "Sales",
    "cell": "E2",
    "formula": "=C2*D2"
  }'

注意：后端限制对文件的访问 sample_files/ 安全目录。调用API时，请使用与该目录相关的路径（例如。 "sales_data.xlsx").

______________________________________________________________________

9.MCP工具（用于LLM）

该项目定义了MCP工具 app/mcp_server.py:

• clean_excel(path: str, sheet: str)
• profile_excel(path: str, sheet: str)
• create_pivot_table(path: str, sheet: str, index: list, values: list, aggfunc: str = "sum")
• insert_excel_formula(path: str, sheet: str, cell: str, formula: str)

LLM（通过MCP感知客户端）将发出如下工具调用：

{
  "tool": "create_pivot_table",
  "arguments": {
    "path": "sample_files/sales_data.xlsx",
    "sheet": "Sales",
    "index": ["Region"],
    "values": ["Revenue"]
  }
}

工具层处理：

• 输入验证（文件存在、工作表存在、列存在）。
• 异常转换为友好的错误消息。
• JSON可序列化响应，带有小预览。

______________________________________________________________________

10.端到端示例场景

LLM的用户提示：

“清理销售Excel文件，并生成按地区显示总收入的透视表。”

LLM行为：

• 选择首次通话 clean_excel:

- {"tool": "clean_excel", "arguments": {"path": "sample_files/sales_data.xlsx", "sheet": "Sales"}}

• 然后打电话 create_pivot_table:

- {"tool": "create_pivot_table", "arguments": {"path": "sample_files/sales_data.xlsx", "sheet": "Sales", "index": ["Region"], "values": ["Revenue"]}}

服务器：

• 清洁纸张并保存清洁后的版本。
• 返回透视表的JSON预览（每个地区的总收入）。

______________________________________________________________________

11.本地LLM演示（Ollama）

此仓库包含一个最小助手(app/llm_client.py)用于当地实验。

1. 确保Ollama正在运行并且模型已被拉动：

ollama pull llama3
ollama serve

1. 在Python shell中使用助手（示例草图）：

from app.llm_client import build_tool_prompt, call_ollama

tools = [
    {
        "name": "create_pivot_table",
        "description": "Create pivot tables over Excel data",
        "schema": {
            "path": "str",
            "sheet": "str",
            "index": "list[str]",
            "values": "list[str]",
            "aggfunc": "str"
        }
    }
]

prompt = build_tool_prompt(
    "Clean the sales Excel file and generate a pivot of total revenue by region.",
    tools,
)

import asyncio
asyncio.run(call_ollama(prompt))

LLM应该用一个JSON对象来响应，该对象描述了要调用的工具和参数，然后您可以将其转发到相应的HTTP端点或MCP工具。

______________________________________________________________________

12.渲染部署（Docker，免费层）

此项目旨在部署在 渲染 使用提供的 Dockerfile.

12.1步骤

• 将此存储库推送到GitHub。
• 在渲染中：

- 创建 新建Web服务. - 连接您的GitHub仓库。 - 运行时：Docker。 - 计划：免费。 - 渲染器将检测 Dockerfile 并构建图像。 - 确保 端口 设置为 10000 （渲染使用 PORT env；相应地配置uvicorn）。

部署后：

• 健康检查： GET https://.onrender.com/health
• 文件： GET https://.onrender.com/docs

12.2冷启动行为

在免费层上，Render可能 向下旋转 不活动后的服务：

• 空闲后的第一个请求可以接受 10-60秒 而容器冷启动。
• 后续请求再次变快，直到稍后空闲。

______________________________________________________________________

13.限制

• 渲染上没有LLM推理：根据设计，所有LLM呼叫（Ollama）都是 仅限本地.
• 临时文件系统 渲染时：

- 容器中写入的Excel文件在重新部署时可能会丢失。 - 对于实际生产，您可以连接耐用的存储或类似S3的存储桶。

• 安全:

- 文件操作仅限于 sample_files/ 目录，但这仍然是一个 演示，而不是一个强化的多租户系统。

• LLM客户端:

- 包括 llm_client.py 故意最小化，而不是一个完整的编排层。

______________________________________________________________________

14.简历准备说明

建立了一种生产风格 LLM驱动的Excel自动化MCP服务器 在Python中，通过以下方式向LLM公开确定性Excel工具（清理、分析、透视表、公式插入） 模型上下文协议 和 快速API.使用以下工具实现了键入的模块化Excel操作 熊猫 和 openpyxl，具有强大的验证和错误处理功能。使用Docker将服务容器化并部署到 渲染的免费层，记录冷启动行为和本地 奥拉玛 工具选择的集成。将代码库和README设计为对招聘人员友好，API层、工具层、Excel逻辑和LLM集成之间有明确的界限。

______________________________________________________________________

15.如何在面试中使用这个项目

• 向招聘人员指出：

- 这 干净的回购结构 并键入带注释的Python代码。 - 这 Excel操作和错误处理 在 app/excel_ops.py. - 这 MCP工具定义 在 app/mcp_server.py. - 这 FastAPI集成 在 app/main.py. - 这 自述 了解架构和部署细节。

• 通过以下方式交谈：

- LLM如何选择工具以及如何保证确定性行为。 - 如何将其扩展到外部存储（S3）、身份验证或更复杂的Excel工作流。

> > > > > > 79937ee（带UI的初始MCP Excel自动化服务器）