Numbers Native

Numbers Native

网站 · 下载 · Italiano · MCP Registry · 支持

由 Viames Marino 打造的 Codex 原生 Apple Numbers 工具。基于 MIT License 开源。

Numbers Native 让 Codex 能通过 Apple Numbers 应用创建、检查和编辑真正的 .numbers 文档。由 Numbers 执行计算并以其原生格式保存。无需转换 Excel、无需 XLSX 库、无需逆向工程文件写入器、无需远程 MCP 服务，也无需额外的 OpenAI API 密钥。

0.5.0 版为预览版。 本地原生验证和可移植性检查并不能证明它与每一台 Mac 都兼容。请参阅验证和功能覆盖范围。

要求

• 安装了 Apple Numbers 并处于已登录图形会话中的 Mac。
• Node.js 22 或更高版本，并且可通过 Codex 主机的 PATH 访问。
• 支持本地 stdio MCP 服务和插件市场的 Codex 环境。
• macOS 中显示的实际主机须获准控制 Numbers，路径为 系统设置 → 隐私与安全性 → 自动化。

此版本使用 Apple Events，无需辅助功能权限。在 Linux/Windows 或隔离的云执行器中，无法运行其原生工具。

在 Codex 中安装

codex plugin marketplace add viames/numbers-native
codex plugin add numbers-native@viames-numbers

启动一个新的本地 Codex 任务并运行设置技能。也可以在兼容的桌面客户端中，通过 添加插件市场 添加 https://github.com/viames/numbers-native。

这个合成示例展示了原生图表更新后的数据：Materiali 为 150 EUR，总计 265 EUR，剩余 35 EUR。

下载发行版

将市场发行包解压到一个固定目录。它包含 .agents/plugins/marketplace.json 和 plugins/numbers-native/。打包的服务包含其 JavaScript 依赖，因此用户无需运行 npm install。

使用较新的 Codex CLI 时，在解压后的目录中运行：

codex plugin marketplace add .
codex plugin add numbers-native@viames-numbers

启动新的 Codex 会话，并调用 @Numbers Native 或其 Numbers/setup 技能。在支持仓库市场的桌面客户端中，将此解压目录作为项目打开，然后在插件中选择 Viames Numbers 市场。主机版本和工作区策略可能会影响市场发现；CLI 注册是显式的。

如果桌面主机找不到 node，请安装 Node.js 并确保它位于该主机的 PATH 中。也可以在兼容客户端的 MCP 配置中直接注册 MCP 服务，并使用解压后服务的绝对路径：

{
  "mcpServers": {
    "numbers-native": {
      "command": "node",
      "args": ["/absolute/path/to/numbers-native/plugins/numbers-native/dist/server.mjs"]
    }
  }
}

原始 MCP 配置是对支持 stdio MCP 的客户端的一种备用方案；它不会安装插件的技能。如果使用此方式，请通过 Codex 原生 TOML 格式配置直接 MCP 连接。请勿将 JSON 粘贴到 config.toml 中。

运行设置，然后试试：

在我指定的文件夹中创建一个原生 Numbers 文档，其中包含两张相互独立的表格，以及用于月度预算的公式。读取合计值并保存 .numbers 文件。

检查我指定的 Numbers 文档，找到 Expenses 表格，并且只更新我提供的值。

覆盖范围和限制

该插件提供 38 个类型化 MCP 工具，用于处理文稿、模板、工作表、表格、区域读取/写入、原生公式、格式设置、清除/合并、排序/转置、行/列、选区、搜索、文本/形状/图像以及现有对象的几何属性。可选的 PDF/CSV 导出由 Numbers 本身执行。

0.5.0 版本新增了带保护的多表格单元格编辑、只读原生结果检查，以及类型化 CSV/TSV 追加/更新。请参阅数据工作流。0.4.0 版本新增了完整的原生/配套备份、恢复和移动/重命名、原生 PDF/PNG 预览（包括引导式前后对比图），以及本地兼容性诊断。请参阅文件/预览工作流。仍支持兼容格式保留、自定义原型和引导式源更新。插件保留了 11 种原生模板图表配置。请参阅新建工作流。支持柱形图、条形图、饼图、圆环图、雷达图、交互式柱形图、堆积柱形图、面积图、双轴图、散点图和气泡图。请参阅图表工作流。双轴图、散点图和气泡图使用固定的轴标题（天气、燃料消耗和销售额）；请按文档说明的数据含义使用。配置已在 Numbers 14.5 中验证；在未经验证的版本或模板结构发生更改时会明确报错。

读取/写入调用限制为 2,000 个单元格；插入/删除行列的调用限制为 100 个项目。大型表格请分批读取。普通字符串均视为字面文本，包括以 = 开头的字符串和前导零。公式必须使用 { "formula": "=SUM(B2:B5)" }。日期必须使用 { "date": "2026-10-18T10:30:00Z" }。布尔值使用原生复选框单元格。Numbers 可能会根据当前文稿语言返回公式和格式化值。

可在新建文稿中根据已验证的模板配置创建图表，最多包含 100 个数据点；每种配置允许的数字列数为 1–10 列。源单元格仍可使用 Numbers 的常规工具编辑；Numbers 会更新关联图表。不支持设置图表类型、数据系列引用、颜色、内部标题，也不支持在现有文稿中的任意位置插入图表。可选标题是单独的原生文本项。暂不支持创建数据透视表、条件规则、批注、协作、密码、详细数字格式和原生复制。

Numbers 会自动保存。写入并非原子操作，可能只部分生效。单个服务内以及协作的多个插件服务之间的调用会串行执行，但用户和其他应用仍可能同时编辑。出错后请检查状态；切勿自动重试超时的变更操作。插件不会关闭无关的文稿。

隐私和本地执行

MCP 桥接不会发起网络请求、监听网络端口、收集遥测数据，也不会将文稿上传到单独的服务。输入和结果会经过 Codex，并可能根据宿主策略发送给其模型。本地自动化并不意味着所有电子表格数据都会留在设备上。

默认情况下，工具可以访问明确选定的本地路径和已识别的打开文稿。若要限制访问，请在 MCP 服务环境中将 NUMBERS_NATIVE_ALLOWED_ROOTS 设置为由现有绝对目录组成的 JSON 数组：

{ "NUMBERS_NATIVE_ALLOWED_ROOTS": "[\"/Users/your-user/Documents/Numbers\"]" }

路径会经过规范化，以拒绝符号链接越界访问。这是额外的桥接检查，并非针对 Numbers 本身的操作系统沙箱。Numbers 可以解析自身的文件依赖项。隐私详情。

开发与验证

npm ci
npm test
npm run build
npm run test:native
npm run test:charts
npm run test:guided
npm run test:files
npm run test:workflows
npm run package

test:native 会启动 Numbers，创建自己的临时文档，并测试这些文档的原生结果。它绝不会将用户文档用作测试样本。此测试需要 GUI/Automation 权限，并且与便携式 CI 分开。单元测试和 MCP 测试可在其他操作系统上运行；原生操作则不行。

发布流程会创建一个市场 ZIP 和一个独立插件 ZIP，其中包含打包的运行时、技能、原生工作进程、声明文件和许可证，并附带 SHA-256 校验和。维护者会使用固定的锁定文件重新构建。独立插件中也包含未打包的源代码，供检查；市场 ZIP 则包含完整的源代码仓库。

公开分发

公开源代码市场是 viames/numbers-native。带版本号的发行版包含 Codex 市场 ZIP、独立插件 ZIP、macOS .mcpb 包、注册表元数据和 SHA-256 校验和。MCPB 客户端可使用相同的原生工具；Codex 插件还包含技能。官方 MCP Registry 标识为 io.github.viames/numbers-native；请查看其实时记录，不要假定注册表提交已成功。通过仓库／注册表分发，与在 OpenAI 官方目录中上架是两回事。

截至 2026 年 10 月 18 日，OpenAI 的仅限桌面端的提交规则将本地 MCP 提交限制为获准的合作伙伴，并要求提交组织列入允许名单。软件包功能完整并不能证明其符合目录收录条件或已获批准。请参阅发布步骤。

Numbers Native 是一个独立项目，与 Apple 或 OpenAI 无关联，也未得到它们的认可。必须安装 Apple Numbers，且本项目不包含该软件。