logisheets-mcp

一个真正让您的AI代理能够进行思考的电子表格引擎。

一个MCP服务器，为任何LLM代理提供一个真正的、兼容Excel的计算引擎——具备它可以按语义寻址的结构化内存，以及最终一个人类可以打开、审计并继续使用的真正的.xlsx文件。

基于LogiSheets构建，这是一个用Rust编写的电子表格引擎。MIT许可，可自行托管，无云依赖。

为什么

代理正在做真正的工作，而这些工作往往是电子表格形态的——财务模型、数据核对、分析——而它们恰恰在电子表格引擎擅长的方面表现糟糕。

算术。 代理会算错总和和乘积。在这里它们不必如此：它们编写一个公式，由确定性引擎来求值。

内存。 在三十步的任务中，中间状态必须存在于某个结构化的地方。上下文窗口是有损且昂贵的；代码沙箱的变量会消失。这个服务器为代理提供了一个外部结构化磁盘，它可以在整个任务中读写。

寻址。 代理不擅长空间推理，所以原始网格是一个脆弱的表面——它们会丢失事物的位置，而它们自己的编辑会破坏它们的引用。因此代理不寻址C7。它寻址**(block, row_key, field)**：

设置revenue块中2025记录的price字段

插入一行，移动块，添加一列——该地址仍然可以解析。这就是全部要点：能够经受住代理自身编辑的内存。

对比Python沙箱

代码解释器可以计算，但你得到的是一个一次性的脚本结果。在这里你得到一个真正的.xlsx，其中仍然包含实时公式——在Excel中打开它，更改一个输入，模型就会重新计算。它可以往返处理人类现有的文件，并且它在你的机器上运行，这在数据不能离开时很重要。

Related MCP server: Excel MCP Server

安装

需要Node 20+。

npm install -g logisheets-mcp

Claude Desktop

添加到claude_desktop_config.json：

{
    "mcpServers": {
        "logisheets": {
            "command": "npx",
            "args": ["-y", "logisheets-mcp"]
        }
    }
}

在macOS上，该文件位于~/Library/Application Support/Claude/claude_desktop_config.json；在Windows上，位于%APPDATA%\Claude\claude_desktop_config.json。之后重启Claude Desktop。

Cursor / Cline / 其他主机

任何能够启动stdio服务器的MCP主机都可以——将其指向logisheets-mcp命令。对于Cursor，将相同的块添加到~/.cursor/mcp.json。

试试看

为我构建一个三年收入模型：100个单位，单价9.50美元，每年增长40%，销售成本为30%。然后将其保存到~/model.xlsx。

代理创建一个块，填充它，编写公式，并交回一个文件。数字是引擎的，而不是模型的猜测——并且.xlsx中包含真正的公式，因此您可以在Excel中更改一个假设并观察它重新计算。

查看其工作方式

npm run build && npm run demo

通过真实的MCP-on-stdio针对dist/cli.js构建一个小型收入模型——与Claude Desktop驱动的相同代码路径——并在进行时检查每个声明：引擎计算的总数、一个能够覆盖后来添加的行的规则、在模型在其下方增长后仍能继续解析的块，以及一个通过读取文件自身字节来验证其公式的真正的.xlsx。不涉及LLM；引擎是主体，硬编码调用是使保证可检查而不是关于聊天会话的故事的原因。

代理循环

list_blocks                     orient: what do I have?
create_block                    open a structured workspace
add_block_rows / set_block_cells    fill it, addressed by (block, key, field)
eval_formula / a stored formula      the engine does the math
describe_block                  read structured results back
save_workbook                   hand the human a real .xlsx

工具

默认表面故意很小——20个工具。随着列表的增长，工具选择准确性会下降，并且每个描述在每一轮都会消耗上下文。

公式与Excel兼容，外加用于语义读取块单元格的BLOCKREF(block, key, field)。在字段规则内部，#FIELD("name")是同一行的兄弟字段，#FIELD("name", "key")是同一块的另一行——即携带该键的那一行，绝不是位置偏移，因此重新排序行不会改变公式的含义。

分析模型，而不仅仅是构建模型

preview_changes接受一个scenarios列表和一个可选的watch，这正是将探索从数十次往返变成一次的原因：

{
  "scenarios": [
    {"label": "wacc 9%",  "changes": [{"block":"assum","row_key":"wacc","field":"v","value":0.09}]},
    {"label": "wacc 12%", "changes": [{"block":"assum","row_key":"wacc","field":"v","value":0.12}]}
  ],
  "watch": [{"block":"valuation","row_key":"per_share","field":"v"}]
}

每个场景在其自己的临时分支上运行并被丢弃，因此实时模型永远不会被触及——没有变异-回滚，如果扫描中途失败也不会留下任何东西。一个4×4的敏感性网格是一次调用返回十六个数字。

goal_seek反向运行相同的技巧——“什么贴现率使每股价值为30”——搜索在引擎内部而不是作为对话进行，因此它是一次调用而不是每次二分步骤一次。当目标在区间内根本无法达到时，它会说明，而不是返回它恰好停止在的最近数字。

trace从引擎的依赖图回答两个审计问题：一个单元格读取什么，以及什么读取它。第二个是它存在的原因——公式文本可以向前读取但不能向后读取，而“如果我更改这个会破坏什么”是您在触及假设之前想要的问题。

读取模型也是语义化的：describe_block返回每个字段的规则，因此代理无需访问单元格即可了解模型的逻辑，公式返回时命名它们读取的内容（B24 / BLOCKREF("assum","shares","v")），而不是您必须追踪的坐标链。

完整表面

设置LOGISHEETS_MCP_TOOLS=full以获得50个工具：撤销/重做、单元格格式、合并、注释、检查点、块移动/调整大小、跨块链接，以及原始行/列结构。

{
    "mcpServers": {
        "logisheets": {
            "command": "npx",
            "args": ["-y", "logisheets-mcp"],
            "env": {"LOGISHEETS_MCP_TOOLS": "full"}
        }
    }
}

变异工具使用MCP的readOnlyHint / destructiveHint注释进行标记，因此主机可以在用户批准后对其进行门控。

块，简要说明

块是工作表的一个命名的、结构化的区域——一个具有模式的表。

• 第一个字段是行键：每个记录的稳定名称。

• 字段可以携带值公式（引擎计算的，因此代理不能将过时的数字写入其中）、验证规则或可编辑性规则。

• 一切都按名称寻址。行和列索引永远不会进入代理的推理过程。

因为块是代理在工作时创建的，这不需要预先准备的文件——您可以将其指向一个空白工作簿或某人发送给您的电子表格。

作为库使用

import {createServer} from 'logisheets-mcp'
import {StreamableHTTPServerTransport} from '@modelcontextprotocol/sdk/server/streamableHttp.js'

const {server, session} = createServer({mode: 'full'})
await server.connect(new StreamableHTTPServerTransport(/* … */))

createServer返回MCP Server、WorkbookSession和工具映射，因此您可以在任何传输上托管它或将其嵌入到代理框架中。

开发

服务器是三个LogiSheets包之上的一个薄壳： logisheets-runtime（无头引擎）、logisheets-logician（代理工具定义）以及Rust/WASM核心。单独处理服务器不需要任何特殊操作：

git clone https://github.com/logisky/logisheets-mcp.git
cd logisheets-mcp
npm install
npm test

同时处理引擎是另一种模式。将LogiSheets作为同级目录检出，构建其包，然后：

npm run link:local     # re-run after any npm install

这将三个包符号链接到node_modules中，以便本地引擎更改无需重新安装即可生效。scripts/release-deps.mjs在发布前将注册表范围放回。

发布

一个标签即可完成。.github/workflows/publish.yaml运行测试，使用来源发布到npm，并向MCP注册表注册新版本：

npm version 0.2.0        # bumps both files, commits, tags v0.2.0
npm run check-release    # optional; CI runs it too
git push --follow-tags

该工作流也可以从Actions选项卡手动运行，此时版本取自package.json而不是标签。npm步骤会跳过已发布的版本，因此在注册表步骤失败的一次运行可以简单地重新运行——两次发布不是事务。

npm version还通过version生命周期脚本重写server.json。注册表在两个地方保留版本——服务器自身的version以及它指向的npm包的版本——而手动编辑它们是最可能被遗漏的步骤。

check-release是门禁。四件事必须一致：标签、package.json以及server.json的两个版本字段。mcpName还必须等于server.json的name，因为注册表通过读取已发布的npm包中的mcpName来证明所有权。npm publish无法撤销——版本号一旦落地就花费了——因此工作流在发布之前运行此检查，而不是之后。

注册表认证不需要秘密：工作流使用GitHub OIDC进行认证，这正是授予io.github.logisky/命名空间的方式。唯一的秘密是NPM_TOKEN。

取回文件

save_workbook写入一个真正的.xlsx，其结果携带一个MCP资源链接——一个uri、媒体类型和大小——而不是文件。工作簿也作为资源列出（workbook://current.xlsx），因此想要字节的主机使用resources/read读取它们并将下载交给人类。

这种分离是重点：工具结果进入模型的上下文，而一个200 KB的工作簿将花费大约280 KB的文本，并且不会教给模型任何东西。链接只花费一行。export_xlsx仍然为根本不实现资源的主机返回base64，但它是后备方案，而不是机制。

读取与工具调用走相同的序列化通道，因此获取文件的主机永远不会捕获到半应用的事务。

open_workbook 和 save_workbook 在服务器进程可访问的任何位置进行读写——这对于本地 stdio 服务器来说是正常的，与官方 filesystem 服务器的姿态相同。两者都被标记为 mutating，以便主机可以在运行前提示；如果需要更严格的限制，请以仅具有预期访问权限的用户身份运行服务器。

状态模型

一个 MCP 会话持有一个活动工作簿，在工具调用之间保持存活——这种持久性使其成为内存而非计算器。open_workbook 会替换它。每个会话多个命名工作簿的功能可能会在以后添加。

无网络

服务器不打开任何套接字，也不监听任何端口。"stdio transport" 是字面意思：您的 MCP 主机将其作为子进程启动，并通过其 stdin 和 stdout 交换换行分隔的 JSON-RPC——与任何命令行程序获得的管道相同。引擎是在同一进程中运行的 WASM，因此公式是函数调用，而不是请求。

检查而非断言。在完整会话之后——创建块、附加字段规则、计算公式、保存 .xlsx——进程持有：

fd types: {CHR: 2, DIR: 4, KQUEUE: 3, PIPE: 6, REG: 13}
network files (lsof -a -i):     0
unix sockets  (lsof -a -U):     0
listening ports:                0

六个管道，无套接字。不上传任何内容，不收集遥测数据，物理隔离的机器是运行此服务器的受支持方式。它在自身内存之外唯一接触的是您指定的文件——请参阅 Getting the file back 下的文件系统说明。

这就是 logisheets-mcp 二进制文件，即 MCP 主机运行的内容。将其 作为库使用 时，您可以附加任何您喜欢的传输方式，包括 HTTP——但那时套接字是您的，是刻意打开的。

许可证

MIT。属于 LogiSheets 项目的一部分。