Local Workbook MCP

Excel本地MCP

  

当地第一 模型上下文协议 该服务器允许AI代理分析和写入Excel工作簿，而无需数据离开您的机器。用自然语言提问，跨表搜索，运行数据透视分析，并通过任何兼容MCP的客户端或附带的web UI更新单元格。

概述 · 特性 · 入门指南 · MCP工具 · 外部客户端 · 配置 · 建筑

______________________________________________________________________

______________________________________________________________________

概述

许多团队无法将财务、人力资源或受监管的Excel文件上传到云服务。 Excel本地MCP 通过在您的机器上完全运行MCP服务器来解决这一问题-LLM原因是在您的数据上不接触外部API。

服务器公开了7个直接映射到Excel操作的标准MCP工具。任何兼容MCP的客户端（Claude Desktop、GitHub Copilot、Cursor、您自己的代码）都可以调用这些工具，或者您可以使用附带的DateTimeweb UI或终端代理。

┌──────────────────────────────────────────────┐
│  Web UI       Terminal Agent    External MCP  │
│ (Blazor)    (Spectre.Console)  (Claude/etc.)  │
└─────────────────────┬────────────────────────┘
                      │  JSON-RPC over stdio
                      ▼
              ExcelMcp.Server
              (ModelContextProtocol SDK)
                      │
                 ClosedXML
                      │
             Excel workbook (.xlsx)

特性

• 隐私第一 --工作簿数据永远不会离开你的机器；LLM通过Ollama或LM Studio在本地运行
• 符合标准的MCP服务器 --建立在 ModelContextProtocol v1.1.0 SDK，兼容任何MCP客户端
• 7 Excel工具 --列表结构、搜索、预览、透视分析、写入单元格、写入范围、创建工作表
• 使用自动备份进行回写 --每个突变都会产生一个时间戳 .xlsx 保存前备份
• Blazon网络聊天 --多轮对话、建议查询、会话导出到CSV/Markdown
• 终端代理 --AS/400启发了由Spectre驱动的REPL。控制台和语义内核
• CLI调试工具 --检查原始MCP工具调用以进行脚本编写和故障排除
• 跨平台 --Windows、Linux、macOS通过。净值10

入门指南

先决条件

\[！提示\] 在Linux上，安装 libgdiplus 要获得完整的ClosedXML支持，请执行以下操作： sudo apt install libgdiplus

1.克隆和构建

git clone https://github.com/McFuzzySquirrel/local-workbook-mcp.git
cd local-workbook-mcp
dotnet build

2.生成示例工作簿（可选）

# Creates ProjectTracking.xlsx, EmployeeDirectory.xlsx, BudgetTracker.xlsx in test-data/
pwsh scripts/create-sample-workbooks.ps1

# Creates SalesWithPivot.xlsx (includes a pivot table)
pwsh scripts/create-pivot-test-workbook.ps1

3.开始你当地的法学硕士

奥利玛（推荐）：

ollama pull llama3.2
ollama serve
# Runs on http://localhost:11434 — auto-detected by the web UI and run-chatweb.sh

LM工作室替代方案： 加载任何模型并在上启动本地服务器 http://localhost:1234。web UI将自动检测到它，但是 run-chatweb.sh 只检查Ollama端点——你会看到一个可以安全忽略的警告。

4.启动web UI

# Linux / macOS
./run-chatweb.sh

# Windows / any platform
dotnet run --project src/ExcelMcp.ChatWeb

打开 http://localhost:5000，在侧边栏中选择您的工作簿，然后开始聊天。

5.或者启动终端代理

dotnet run --project src/ExcelMcp.SkAgent -- --workbook "path/to/your/workbook.xlsx"

代理运行后的示例查询：

> What worksheets are in this workbook?
> Show me the first 10 rows of the Tasks sheet
> Search for 'Alice' across all sheets
> What does the SalesPivot pivot table contain?
> Update cell B2 in the Projects sheet to "Completed"

CLI Screenshot

______________________________________________________________________

MCP工具

服务器向任何MCP客户端公开以下工具。所有工具都接受可选 workbook_path 参数；如果省略，服务器将回退到 EXCEL_MCP_WORKBOOK 环境变量。

______________________________________________________________________

与外部MCP客户端一起使用

因为服务器通过stdio使用标准MCP，所以任何兼容的客户端都可以直接使用它。

克劳德桌面版

添加到您的Claude Desktop配置文件中：

• macOS： ~/Library/Application Support/Claude/claude_desktop_config.json
• 窗户： %APPDATA%/Claude/claude_desktop_config.json

{
  "mcpServers": {
    "excel": {
      "command": "/path/to/ExcelMcp.Server",
      "args": ["--workbook", "/path/to/your/workbook.xlsx"]
    }
  }
}

已准备好合并的代码段位于 mcp配置/claude_desktop_configure.json.

光标

合并 ~/.cursor/mcp.json --看 mcp配置/cursor_mcp_config json.

GitHub副本/VS代码代理模式

创建 .vscode/mcp.json 在您的工作区中，指向服务器可执行文件。

\[！注意\] 服务器二进制文件的构建目的是 src/ExcelMcp.Server/bin/Debug/net10.0/ExcelMcp.Server （或 .exe 在Windows上）。使用 scripts/package-server.ps1 生成自包含的可分发脚本。

______________________________________________________________________

命令行客户端

ExcelMcp.Client 是一个轻量级的CLI，用于直接调用MCP工具。可用于脚本编写、冒烟测试和调试工具有效负载。

export EXCEL_MCP_SERVER="src/ExcelMcp.Server/bin/Debug/net10.0/ExcelMcp.Server"
export EXCEL_MCP_WORKBOOK="test-data/ProjectTracking.xlsx"

# Available commands
dotnet run --project src/ExcelMcp.Client -- list
dotnet run --project src/ExcelMcp.Client -- preview Tasks --rows 5
dotnet run --project src/ExcelMcp.Client -- search "High priority"
dotnet run --project src/ExcelMcp.Client -- analyze-pivot SalesPivot
dotnet run --project src/ExcelMcp.Client -- write-cell --sheet Tasks --cell G1 --value "Done"
dotnet run --project src/ExcelMcp.Client -- write-range --sheet Tasks --range A10:B10 \
  --data '[{"cellAddress":"A10","value":"New Task"},{"cellAddress":"B10","value":"Open"}]'
dotnet run --project src/ExcelMcp.Client -- create-worksheet "Summary"

涵盖所有4个示例工作簿的自动烟雾测试脚本位于 脚本/测试/手动测试cli.sh （35/35通过）。

______________________________________________________________________

配置

Web用户界面

中的关键设置 src/ExcelMcp.ChatWeb/appsettings.json:

{
  "SemanticKernel": {
    "BaseUrl": "http://localhost:11434/v1",
    "Model": "llama3.2",
    "ApiKey": "not-needed-for-local",
    "TimeoutSeconds": 480
  },
  "ExcelMcp": {
    "ServerPath": "src/ExcelMcp.Server/bin/Debug/net10.0/ExcelMcp.Server"
  },
  "Conversation": {
    "MaxContextTurns": 5,
    "MaxResponseLength": 10000
  }
}

这 BaseUrl 自动检测：Ollama(localhost:11434)首先尝试，然后是LM Studio(localhost:1234).

覆盖开发 appsettings.Development.json.

终端代理

通过环境变量进行配置：

# Ollama (default — auto-detected)
export LLM_BASE_URL="http://localhost:11434/v1"
export LLM_MODEL_ID="llama3.2"
# or LM Studio
export LLM_BASE_URL="http://localhost:1234/v1"
export LLM_MODEL_ID="local-model"
export EXCEL_MCP_WORKBOOK="/path/to/workbook.xlsx"

______________________________________________________________________

测试

57次用户验收测试 涵盖所有4个示例工作簿和写入操作：

dotnet test tests/ExcelMcp.UAT/ExcelMcp.UAT.csproj

手动测试检查表 对于web UI（43个步骤）： scripts/tests/manual-test-chatweb.md

自动化CLI烟雾测试 （35个自动验证+2个手动验证跳过）：

./scripts/tests/manual-test-cli.sh
# Filter to a single workbook group:
./scripts/tests/manual-test-cli.sh --workbook ProjectTracking

______________________________________________________________________

建筑

该系统遵循 六角形/端口和适配器 适用于MCP的模式。服务器是一个孤立的进程；UI和代理层仅通过MCP协议与其通信。

src/
├── ExcelMcp.Server/       # MCP server — 7 tool handlers, ClosedXML backend
├── ExcelMcp.Contracts/    # Shared sealed-record DTOs
├── ExcelMcp.ChatWeb/      # Blazor Server web UI + Semantic Kernel orchestration
├── ExcelMcp.SkAgent/      # Terminal REPL agent (Spectre.Console + SK)
└── ExcelMcp.Client/       # CLI debug and scripting client

看 docs/Architecture.md 查看完整的序列图和组件描述。

\[！注意\] UI层从不导入 ExcelMcp.Server 直接。所有数据都通过JSON-RPC工具调用流动，这意味着相同的服务器二进制文件对web UI、终端代理、Claude Desktop和Cursor的工作方式相同。

______________________________________________________________________

资源

• 模型上下文协议规范
• 模型上下文协议。NET SDK
• Microsoft语义内核文档
• 已关闭XML --Excel处理库
• LM 工作室 · 奥拉玛 --本地LLM选项
• docs/UserGuide.md --详细的设置和使用指南
• docs/FutureFeatures.md --路线图

______________________________________________________________________

*这个项目源于一个简单的问题：“我可以在不将电子表格发送到云端的情况下与它聊天吗？”这里的一切都是一个学习实验——在开放的环境中构建，共享，以防对其他人有用。*