ExcelMCP

面向AI智能体的实时Excel智能层。 将其指向OneDrive文件夹，你的智能体即可用自然语言查询这些电子表格中的实时数据。

解决的问题

大多数电子表格集成的工作原理是将数据复制到其他地方。它们会摄取工作簿，将其分块，嵌入单元格值，并将所有内容存储在向量数据库中。从那一刻起，你的智能体就在基于快照回答问题。有人在上午9点更新了库存表，但智能体仍在引用周二的数字。

ExcelMCP 将问题一分为二。

结构会被缓存。 文件名、工作表名、列标题、标题行的起始位置、哪些列包含日期、工作表之间的关联关系——以及每个低基数列的一小部分不同标签样本，这正是在上百个几乎相同的工作表之间进行路由的关键。这些信息很少变化，存储成本低廉，并且是智能体了解“要请求什么”所必需的。（采样的标签是结构触及值的唯一位置；具体边界在磁盘上的存储内容中说明。）

数据永远不会被缓存。 每个返回数字的工具调用都会访问Microsoft Graph API并实时拉取数据。不存在会过时的数据缓存，不存在会落后的同步任务，也绝不会从磁盘提供任何答案。

每个响应都带有 metadata.fetched_at 时间戳和 is_cached: false 标志，以便模型可以通过带内信号了解到自己看到的是最新数据。

Related MCP server: Microsoft 365 MCP Server

工作原理

一个自然语言问题被嵌入，通过余弦相似度与工作表描述进行匹配，然后按与列名和采样值的词法重叠进行重新排序——这使得当二十个工作簿共享一个模式时，路由仍然有意义。这些工作表（且仅有这些工作表）会被实时获取。随后，过滤和聚合操作在 pandas 中对刚刚获取的数据帧进行。单值问题完全跳过行处理管道：lookup 读取一个关键列和一行，并返回带有其来源的单元格。

环境要求

• Python 3.10 或更新版本

• 一个包含 OneDrive 的 Microsoft 365 账户

• uv，或者如果你愿意，也可以使用普通的 pip

安装

在仓库根目录下运行：

git clone https://github.com/Karunya-Muddana/ExcelMCP.git
cd ExcelMCP

uv sync      # install dependencies
uv build     # build the wheel
pip install dist/excelmcp-0.3.0-py3-none-any.whl

或者直接从源码安装，无需构建：

pip install .

无需编译步骤，也无需构建原生扩展。向量搜索在 NumPy 的余弦扫描上运行，而非 hnswlib，这专门是为了确保在没有 C++ 工具链的机器上也能使用 pip install 安装。

设置

运行一次设置向导：

excelmcp-setup

该向导引导完成四件事：

1. Microsoft 设备流登录。你会得到一个代码，将其粘贴到浏览器中，令牌缓存会以 0600 权限保存在 ~/.excelmcp/token.json 中。

2. 要索引的 OneDrive 文件夹，例如 /ERP。

3. 扫描该文件夹中的每个 .xlsx 文件，以构建结构图和嵌入向量。

4. 检测你机器上已安装的 AI 智能体，并为你选择的智能体写入配置条目。

可自动配置的智能体

在修改现有配置文件之前，会先进行备份。如果你的智能体不在列表中，向导会打印出需要手动粘贴的精确 JSON 或 TOML 代码块。

其他向导命令

excelmcp-setup list-agents           # show what was detected
excelmcp-setup install --only cursor # register with one agent, skip the rescan
excelmcp-setup doctor                # diagnose a broken install
excelmcp-setup uninstall             # remove ExcelMCP from every agent config
excelmcp-setup --folder /ERP --yes   # fully non-interactive
excelmcp-setup --dry-run             # print the changes, write nothing

向智能体暴露的工具

两个结构工具是免费且即时的，因为它们读取本地图。标记为“实时”的所有内容每次调用都会访问 API。

使用方法

注册服务器后，你通常可以像平常一样与你的智能体对话。在幕后，它会进行如下调用。

首先进行定向。在猜测列名之前，智能体应该始终这样做，因为没有两家公司会以相同的方式命名事物：

get_workspace_graph(folder_path="/ERP")

在不知道答案所在位置的情况下提问：

query("what are the top 10 products by sales value", folder_path="/ERP")

过滤已知的工作表：

filter_sheet(
    file_name="Inventory.xlsx",
    sheet="Stock",
    conditions={"Status": "Low", "Quantity": "<50"},
    folder_path="/ERP",
    sort_by="Quantity",
    limit=100,
)

支持的条件运算符，全部进行 AND 操作：

不存在的列名或运算符会引发错误，而不是静默返回零行，后者是导致智能体自信地报告错误信息的失败模式。当条件确实没有匹配项时，响应会包含 zero_match_diagnostics——每个条件单独匹配了什么，以及有问题的列中存在的多达二十个实际值——这样近乎匹配的错误会被纠正，而不是报告为“无数据”。

一次调用请求单个数字：

lookup(query="contracted rate for Titanium Dioxide under the BESTEX contract",
       folder_path="/Contracts")

答案会附带来源信息（文件、工作表、单元格地址、匹配的行）和一个置信度字段。多个匹配行会返回 ambiguous 并列出所有行；工作表之间的结果不一致会返回 conflict 并列出所有版本，不提供单一值；拼写错误的关键字会返回模糊建议。该工具从不返回一个裸数字。

在单个文件内进行分组和聚合计算：

aggregate(
    file_name="Sales.xlsx",
    sheet="Q1",
    group_by="Region",
    value_col="Revenue",
    operation="sum",
    folder_path="/ERP",
)

汇总工作区中所有文件中的同一个工作表：

cross_file_aggregate(
    sheet="Q1",
    value_col="Revenue",
    operation="sum",
    folder_path="/ERP",
    conditions={"Status": "Closed"},
)

cross_file_aggregate 会返回每个文件的详细结果以及总计，还会在无法读取某个文件时返回 skipped_files，并为每个不包含确切工作表名称的文件返回 unmatched_files（附带 did_you_mean 候选名称）。这样，部分总计就会明显是部分的，而不是静默地给出错误结果，包括其中某些文件中的工作表名为 Sales 而其他文件名为 Sales 2024 的情况。在进行聚合之前，请检查 get_workspace_graph 中的 sheet_name_variants，以预先了解这种碎片化情况。

智能体操作指南

安装服务器只是成功的一半。agents/ 文件夹涵盖了另一半：如何提示一个拥有这些工具的智能体，如何将其集成到每个宿主环境中，以及一旦它正常工作后可以自动化处理什么。

服务器内置的安全护栏

服务器在其 MCP 指令中附带了一套操作规则，宿主模型在首次调用前会读取这些规则。它们的存在是因为 LLM 在处理电子表格问题时，容易以特定的方式出错：

• 切勿假设文件名、工作表名称或列名。请从图中发现它们。

• 切勿在脑中累加跨文件数字。请调用 cross_file_aggregate 让工具完成。

• 切勿使用 openpyxl、pandas.read_excel 或本地文件系统。这些文件不在本机上。

• 切勿直接对交易型数据的数量列求和——请使用 derive 并明确指定交易类型。

• 日期列作为 ISO-8601 字符串到达，已由服务器从序列号转换而来。切勿手动进行序列号算术运算。

• 对于单个数据，请调用 lookup 并引用其返回的出处；遇到其 ambiguous 和 conflict 结果时，不要自行选择值。

• 在声称结果完整之前，请检查 truncated 和 total_matched 字段。

忽略服务器指令的宿主，以及你自己构建的自定义代理，需要在其自身的提示词中明确声明这些规则。参见 agents/system-prompt.md。

配置

内置的客户端 ID 是一个用于设备代码流的公共客户端。它不包含任何秘密，有意在每个认证请求中可见，并且保留在此仓库中是安全的。如果你希望同意屏幕显示你组织的名称，请将其替换为你自己的应用注册。

写入磁盘的内容

~/.excelmcp/
  token.json           MSAL token cache. Auth material only, written 0600.
  graph.json           Structure graph: item IDs, sheet names, column headers,
                       used-range dimensions, date column types, per-sheet
                       table regions, inferred and formula-declared
                       relationships — and sampled values (see below).
  vectors.npy          Embedded sheet descriptions for semantic routing.
  metadata.json        Labels and lexical terms tying each embedding to a sheet.
  relationships.yaml   Optional, written by you: declared join relationships.

截至 0.3.0 版本，关于无缓存声明的真实情况。 你的数据的任何行、任何单元格网格或任何可查询的值都不会存储在磁盘上——每个答案都始终来自实时获取。有一个故意的例外：graph.json 存储了采样值，每个低基数列（客户名称、状态、物料名称、单位）最多 50 个不同的文本标签，在扫描时捕获。它们的存在是为了让一百个结构相同的工作表在路由问题时能够被区分，让 lookup 能够找到包含“BESTEX”的那个工作表而无需下载所有内容，并且可以根据值的重叠而不是列名来推断关系。它们是路由证据，而不是数据缓存：没有任何东西会基于它们来回答问题，工作区扫描会整体刷新它们。该图还存储了每个工作表的指纹（表头列和已用范围地址），纯粹用于检测变化，以及——0.3.0 版新增的——一个区域映射：工作表中每个表格体的行跨度，来源于工作表自身的 SUM/COUNT/AVERAGE 公式引用的范围，加上任何跨工作表公式读取的地址。这些是行号和单元格地址，而不是内容；不读取任何值来生成它们。区域的 label（如果存在）是采样值之外的第二个故意例外：从区域正上方的节标题单元格读取的几个词（例如 “NAPHTHALENE”、“OLEUM 65%”），以便模型能够命名它所指的表格，而不是根据行号猜测。它是描述工作表布局的结构性元数据，而不是行数据——这与采样值已经划定的界限相同。如果这些内容中有任何超出你希望保留在磁盘上的范围，请不要扫描该文件夹；如果你想验证这个边界，graph.json 很小且可读，可以自行查看。

在 Windows 上，os.chmod 只能切换只读位，因此 0600 模式在那里是尽力而为，真正的保护是 %USERPROFILE% 上默认的每用户 ACL。在 macOS 和 Linux 上，该模式在写入任何内容之前应用于临时文件，因此令牌永远不会短暂地以全局可读状态存在。

测试

# offline unit tests, no network and no credentials required
pytest tests/test_unit.py

# live integration tests against a workspace you have already scanned, opt in
EXCELMCP_TEST_FOLDER=/ERP pytest tests/test_live_integration.py -v

当 EXCELMCP_TEST_FOLDER 未设置时，集成测试套件会自动跳过自身，因此直接运行 pytest 将保持离线状态。

项目布局

agents/           prompts, host guides, and schedulable routines
auth.py           MSAL device flow, token cache, proactive refresh
graph_client.py   Graph API wrapper, 429 backoff, shared concurrency gate
structure.py      Structure discovery, value sampling, relationship inference
embeddings.py     FastEmbed vectors, NumPy cosine search, lexical rerank
query_engine.py   Conditions, live fetch, aggregation, joins, derive
lookup.py         Single-cell lookup pipeline and get_cell
ranges.py         A1-notation range arithmetic
main.py           FastMCP tool definitions and server entry point
cli.py            Setup wizard, agent detection, config writing
agents.py         Per agent config formats and file locations
storage.py        Atomic writes, stderr logging, config directory handling

贡献

欢迎提交 issue 和 pull request。如果你要添加对其他代理的支持，只需要修改 agents.py 这一个文件：添加一个包含配置路径、条目形状和检测提示的 AgentSpec。

许可证

MIT。参见 LICENSE。