Basis

@basis1/mcp

面向 AI Agent 的 Excel 引擎。 让 AI Agent 读取、检查和编辑 Excel 模型。

一个适用于 Basis 的 MCP 服务。它让 Claude、Cursor 和其他 MCP 客户端能够解析 Excel 工作簿、计算公式、追踪依赖关系，并将工作簿作为会话打开，以便修改输入并读取结果。

每个工具都通过 Basis API 运行。 你需要 Basis API 密钥和网络连接，并且提供给工具的工作簿会上传到 Basis API：https://api.basis1.tech。请参阅上传了哪些内容。

安装

你需要 Node.js 20.19 或更高版本，以及一个 Basis API 密钥。你可以在账户设置中自行创建密钥：basis1.tech/settings。下面的每个代码片段都会通过 npx 启动服务，并在首次运行时下载软件包。

Claude Desktop

打开设置 → 开发者 → 编辑配置，将以下内容添加到 claude_desktop_config.json，然后重启 Claude Desktop：

{
  "mcpServers": {
    "basis": {
      "command": "npx",
      "args": ["-y", "@basis1/mcp"],
      "env": {
        "BASIS_API_KEY": "your-api-key"
      }
    }
  }
}

Claude Code

claude mcp add basis --env BASIS_API_KEY=your-api-key -- npx -y @basis1/mcp

添加 --scope user，即可在每个项目中使用；添加 --scope project，即可通过项目的 .mcp.json 与他人共享。在共享文件中，写入 "BASIS_API_KEY": "${BASIS_API_KEY}"，这样每个人使用的密钥都来自各自的环境。

Cursor

将以下内容添加到 ~/.cursor/mcp.json，或项目中的 .cursor/mcp.json：

{
  "mcpServers": {
    "basis": {
      "command": "npx",
      "args": ["-y", "@basis1/mcp"],
      "env": {
        "BASIS_API_KEY": "your-api-key"
      }
    }
  }
}

其他 MCP 客户端

将 stdio 服务配置为使用命令 npx 和参数 -y @basis1/mcp，并在其环境中设置 BASIS_API_KEY。在 Windows 上，如果客户端无法直接启动 npx，请使用命令 cmd 和参数 /c npx -y @basis1/mcp。

无需安装：托管端点

如果你的客户端支持通过自定义标头使用 HTTP 连接远程 MCP 服务，你可以直接连接托管端点，无需运行此软件包：

{
  "mcpServers": {
    "basis": {
      "type": "http",
      "url": "https://api.basis1.tech/mcp",
      "headers": { "Authorization": "Bearer your-api-key" }
    }
  }
}

在 Claude Code 中：claude mcp add --transport http basis https://api.basis1.tech/mcp --header "Authorization: Bearer your-api-key"。

它提供相同的工具，但无法读取你电脑上的文件：请传入 url 或 base64，而不是 path。此软件包通过读取你电脑上的文件并代为上传，提供对 path 的支持。

设置

变量	默认值	作用
BASIS_API_KEY	none (required)	你的 Basis API 密钥。未设置时服务仍会启动，但每个工具都会提示缺少密钥。
BASIS_BASE_URL	https://api.basis1.tech	要使用的 Basis API，例如可自托管的服务。除非指向 localhost，否则必须使用 https://，以确保密钥始终经过加密传输。
BASIS_MCP_MAX_FETCH_BYTES	200000000	通过 url 传入时，工具会下载的最大工作簿大小。

密钥的旧名称 BASIS_TOKEN 仍然有效，并会记录提醒，建议将其重命名。

如果设置无效，服务不会启动：它会将需要修正的内容写入 stderr，MCP 客户端会在服务日志中显示这些信息（Claude Desktop：设置 → 开发者；macOS 上的位置为 ~/Library/Logs/Claude/mcp-server-basis.log）。服务只会向 stderr 写入诊断信息，因为 stdout 承载 MCP 协议；它绝不会输出你的密钥。

npx -y @basis1/mcp --help 会列出这些设置，--version 会输出版本。

工具

工作簿输入必须且只能指定以下其中一项：path（电脑上的文件）、url 或 base64。

解析

• parse_workbook：以 NDJSON 记录形式返回工作簿（workbook_meta、sheet、cell、edge、image、image_summary、audit）。大型文件会作为后台任务运行，并自动轮询直至完成。
• submit_job：启动解析任务并返回其句柄（job_id、status_url、stream_url），不等待任务完成。
• get_job_status：获取任务状态。
• stream_job：获取已完成任务的 NDJSON 输出，可选择从记录 since 开始。
• diff_workbooks：比较两个工作簿的单元格级差异：新增、删除和变更的单元格（值和／或公式），并单独列出仅格式变更。接受 before_* 和 after_* 输入以及 include_format。

公式

• evaluate_formula：根据你提供的单元格值计算一个 Excel 公式，例如 {"formula": "NPV(0.08,A1:A5)", "data": {"A1": 100, ...}}。支持 278 个 Excel 函数，包括财务、统计、查找和动态数组函数。

重新计算文件

• recalc_workbook：接受一个 .xlsx（path、url 或 base64），并返回已将计算值保存到每个公式单元格中的文件，以及相同的错误摘要。在你使用 openpyxl（或任何会保存公式但不保存计算结果的库）创建或编辑工作簿后调用它：否则，pandas、openpyxl data_only=True 和其他非 Excel 读取器看到的都是空单元格。传入 output_path 可将结果写入你的计算机；输入路径与输出路径相同并设置 overwrite: true 时，会在原文件上重新计算。文件会上传用于计算，但不会被保留。

这两个返回文件的工具会逐字节保留 Basis 无法建模的内容（样式、图表、图像、数据验证、条件格式、定义名称、批注、.xlsm 中的 VBA）。无法保留的内容会列在 summary.warnings 下：单元格文本中的逐词格式、假设分析数据表，以及多单元格数组公式的缓存结果。Basis 无法计算的公式会列在 summary.uncomputed 中，而不会在不作提示的情况下保存为空白。

工作簿会话。 会话会在 Basis API 上保持一个工作簿处于打开状态，供你逐步修改。

• create_session：从 path、url、base64 或你的 Library（library_file_id）打开工作簿，或新建空白工作簿。可选的 calc 参数会启用迭代计算。本地 path 会包含在单个请求中传输，因此目前超过约 24 MB 的文件无法作为会话打开；大型文件可使用 parse_workbook 处理。
• list_sessions、close_session。
• set_inputs：通过定义名称或单元格引用设置值或公式，重新计算，并报告哪些命名输出发生了变化。
• get_outputs：通过名称、单元格引用或区域（Sheet1!H2:H18）读取计算值，或读取所有定义名称。
• define_variable：创建或重新指定定义名称。
• add_sheet：向空白工作簿添加工作表。
• rename_sheet：重命名工作表；引用该工作表的公式、定义名称和验证规则会随之更新。
• set_calc_settings：为循环模型启用或关闭迭代计算。
• inspect_model：查看工作表、定义名称、计算设置和统计信息，也可选择查看依赖关系图。
• get_cell_formula、get_formula_range：获取单元格或区域的公式和值。
• trace_dependencies：追踪单元格的前置单元格和从属单元格，最多深入 5 层。
• audit_workbook：对工作簿进行结构审计（错误、失效引用、循环、命名区域）。
• commit_session、restore_session：命名检查点并回滚。
• export_workbook：重新计算会话，并将其作为 .xlsx 返回，文件中会保存每个公式的计算值，另附公式错误摘要（#REF!、#DIV/0!、#NAME? 及对应的工作表和单元格）。传入 output_path 可将文件写入你的计算机，而不是以 base64 返回（使用 overwrite: true 可替换现有文件）。
• snapshot_session：将当前工作簿作为 .xlsx 字节（base64）返回，不含摘要。建议优先使用 export_workbook。
• save_to_library：将工作簿作为新文件或新版本保存到你的 Basis Library。

工具错误会以工具结果的形式返回，其中 isError 设为 true，并附带 JSON 正文 {"code", "message", "status"}，例如 missing_api_key、unauthorized、network_error、session_not_found 或 API 的某个错误代码。

上传的内容

• 解析和差异比较： 工作簿会发送到 Basis API。解析任务及其结果仅保存在服务的内存中，并会在 15 分钟后过期。
• 公式： 你传入的公式和单元格值会发送到 Basis API。
• 会话： 创建会话时会上传工作簿，并在操作期间保留在 Basis API 上。会话在 30 分钟未使用后关闭，或在你调用 close_session 时关闭。为确保服务重启后会话仍然可用，会话状态也会备份到私有云存储中；这些检查点会在一天内删除。
• Library： save_to_library 会将工作簿存储在你的 Library 中，直到你将其删除。
• 计算机上的文件： 工具会读取你传入的 path 并上传该文件的内容，不会读取其他内容。
• URL： 此软件包会在你的计算机上下载你传入 parse_workbook、submit_job 或 diff_workbooks 的 url，并上传字节数据。对于会话，Basis API 会自行下载该 URL。

所有流量均使用 HTTPS，API 密钥通过 Authorization 标头传递。如果你的工作簿不能离开计算机，请勿对其使用此服务。

开发

在此仓库的检出目录中：

(cd ../sdk && npm ci && npm run build)  # @basis1/parse, linked as file:../sdk
npm ci
npm run build                            # typecheck, then bundle dist/index.js
npm test                                 # unit, hosted forwarding and stdio handshake tests
npm run test:pack                        # pack, install in a temp dir, MCP handshake over stdio

要让构建连接到其他 Basis 服务，例如可自托管的服务：

BASIS_API_KEY=devtoken BASIS_BASE_URL=http://localhost:8080 node dist/index.js

包的构建方式

dist/index.js 是一个单独的 esbuild bundle，其中包含 @modelcontextprotocol/sdk 和 zod（两者均采用 MIT 许可证）。如果将它们作为运行时依赖，每次首次运行 npx 时都会安装 95 个包（23 MB），其中还包括 stdio 服务从不使用的 Web 服务框架。打包后，npx 只需安装两个包，并运行我们测试过的确切版本。它们的许可证文本随附于 dist/THIRD_PARTY_LICENSES.txt，如果打包的包未采用宽松许可证，构建就会失败。

@basis1/parse 是真正的运行时依赖，并未打包。在仓库中，它指向 file:../sdk。发布流程会在发布前将其改写为 ^<sdk version>，而 scripts/check-publishable.mjs 会拒绝仍包含本地路径的包。

发布

发布由维护者负责。当一项更改涉及两个包时，会先发布 SDK，然后发布依赖已发布 SDK 版本的 MCP 服务。package.json 和 server.json 中的 version 会保持同步。

MCP Registry

server.json 将此服务描述为 MCP Registry 中的 tech.basis1/mcp，而 package.json 中的 mcpName 则将 npm 包与其关联。tech.basis1/ 命名空间属于 basis1.tech 域名，而非个人 GitHub 账号，因此 Registry 会通过 DNS 对其进行验证。系统不会自动提交任何内容。

npm 发布后，维护者会登录并使用 mcp-publisher login dns --domain basis1.tech，在 Registry 中登记每个版本。tech.basis1/ 命名空间通过 basis1.tech 上的 DNS 记录进行验证。

许可证

Apache-2.0。详见 LICENSE。