Microsoft Project

Horizun Project MCP

一款适用于 Microsoft Project 的 MCP 服务，无需 Java 或 Microsoft Project——并且会如实告知你写入了什么。

它充当 PMO，而非软件操作员。 它不会只替你点击 Microsoft Project：它遵循 PMBOK，按照项目管理办公室的方式进行规划、控制和报告——遵守 100% 规则的 WBS、加载成本的基准、挣值和挣值进度、定量进度风险分析、说明原因并由审批人确认的正式变更控制、包含 PPC 的每周前瞻规划，以及带趋势分析的周期状态报告。Project 是引擎；方法才是产品。

西班牙语

让任何 MCP 客户端连接到 .mpp、Primavera .xer 或 MSPDI .xml，然后提出实际问题：关键路径在哪里、哪些资源超额分配、进度计划能否通过 DCMA 审计、延误两周实际上会如何影响完工日期。然后将变更写回——并确认哪些变更已生效，因为每项变更都会在报告前从模型中重新读取。

dotnet tool install -g HorizunMsProjectMcp

这就是全部安装步骤。不需要 JVM。不需要 Microsoft Project。不需要许可证。它可以独立读取并安排计划。

连接客户端

客户端	操作
Claude Desktop	从 Releases 下载 .mcpb，并将其拖放到 Settings → Extensions。它会自行安装服务——无需预先运行任何内容。
Claude Code	claude mcp add horizun-msproject-mcp -- horizun-msproject-mcp
Codex	codex mcp add horizun-msproject-mcp -- horizun-msproject-mcp
ChatGPT	需要在 stdio 服务前配置 HTTPS 桥接。了解方法，以及需要优先考虑的因素。

各客户端的完整说明，包括插件安装方式和卸载方法，请参阅 docs/INSTALL.md。

---

为什么选择它

目前有少数几个 Microsoft Project MCP 服务。但它们无一例外都需要 Java、已获许可的 Microsoft Project 安装，或付费 JDBC 驱动；而在构建此服务的机器上，它们一个都无法启动。这里有 8 项其他任何地方都没有的功能：

零前置条件	一个 .NET 二进制文件。MPXJ 通过 IKVM 编译为 .NET，因此整个方案中完全不需要 JVM，也不需要 Microsoft Project。
使用 Microsoft Project 自己的日期，而非仿制结果	安装了 Project 时，本服务报告的每个日期都由 Project 自己计算。在 7 个真实进度计划（共 8,823 个任务）上，通过它进行的重新计算和编辑，在每个任务上都与 Project 一致，精确到分钟。具体方式。
经验证的写入	Microsoft Project 经常会静默忽略写入——自动计划的日期、硬性约束、汇总任务汇总值、计算得出的成本都可能如此。只有从模型中重新读取并核对匹配后，这里才会报告写入已应用。
DCMA 14 点评估	用于判断进度计划是否可执行的行业标准。Primavera 服务已实现该功能；Microsoft Project 服务则无一实现。第 12 项检查会实际注入 600 天的延误，并测量发生了哪些变化。
找回无人建立关联的逻辑关系	进度计划在横道图上排布正确，却从未建立逻辑关系，这是最常见的缺陷：DCMA 会标记它，但没有任何工具能修复它。日期已经表明了顺序——本工具会从中还原顺序，验证这一顺序在每次重复中都成立，并提出缺失的链接。
经测算的重新计划	恢复方案会应用于进度计划副本，重新排程，并报告实际实现的完工日期。无法缩短工期的方案会如实说明，而不会作为建议提供。
从以往项目中学习	指向已完工的进度计划后，它会报告每项活动实际耗时以及通常的前置活动，然后据此起草新的计划——每个单元一个任务，并按照各工种实际的衔接顺序排序。
BIM 桥接	按代码将进度计划任务关联到模型构件，将实测工程量转换为工期建议，并输出各构件的日期，用于驱动 Navisworks 中的 4D 展示和 Power BI 中的进度仪表板。其他工具完全做不到这一点。

---

27 个工具

会话 — project_health · project_open · project_save

project_health 是医生，不是连通性检测。它会检测 Microsoft Project，测试其 COM 服务器是否真的能启动；如果无法启动，则会返回 HRESULT 诊断信息和修复步骤。这并非假设情况：这台机器遇到了 CO_E_SERVER_EXEC_FAILURE，尽管注册完全有效；它输出的修复流程中，第一步就是解决问题的办法。

读取 — project_info · tasks_query · links_query · resources_query · timephased_query

支持筛选、分页和选择字段。任务通过稳定的 uid 标识；行 id 仅用于显示，因为插入任务后它会立即变化，按它定位会编辑错误的任务。

分析 — schedule_analyze · schedule_qa · baseline_compare

在服务端计算，让 Agent 只需提出问题，无需将 2,000 个任务拉入上下文。关键路径、时差分布、驱动路径、逐日总体资源过度分配、DCMA-14，以及完整的挣值分析（BCWS/BCWP/ACWP、SPI、CPI、EAC、TCPI）——进度计划包含成本时以成本计量，包含工时时以工时计量，两者都不包含时则按工期加权，而大多数进度计划都属于这种情况。报告会说明采用了哪种计量方式。

写入 — tasks_write · links_write · resources_write · calendars_write · schedule_update 批量、类型安全、经过验证。循环依赖会在应用前被拒绝，并指出问题链条。 日历会完整编辑：工作周及其工时（半天或全天周六、轮班），带工时的工作与非工作例外、项目日历，以及任务和资源日历。任务可一次批量设置类型、投入驱动标记、固定成本、不会更改基线日期的基线成本，以及完整的大纲；资源可设置 Project 实际识别的费率、加班费率、材料单位和最大单位数。schedule_update 的 level_resources 操作使用 Microsoft Project 自带的资源平衡器进行平衡，也可选择仅在时差范围内平衡。有一项功能不提供：将任务移到大纲中的其他位置。提出这项请求会收到明确指出该操作的拒绝，因为半成品功能不如没有功能。

规划 — schedule_recovery · schedule_scenarios · schedule_target · schedule_sequence · schedule_learn · schedule_generate

重新规划，靠衡量而非断言。schedule_recovery 找出哪些工作已延误，按其后方积压的进度量排序，然后在临时副本上逐一尝试各种恢复手段——消除关键路径上的时滞、在前置任务完成一半后让交接工作重叠、压缩最长的关键任务、周六全天工作，以及组合使用所有手段——并报告每种手段实际能实现的完工日期，以及任何手段被舍弃的原因。schedule_scenarios 并排比较你定义的备选方案——将日历、资源、任务和逻辑变更组合起来——展示完工时间、成本、资源过度分配情况、关键任务，不会提交任何更改。schedule_target 会验证给定的目标日期，并指出网络计划无法固定在该日期内完成的工作。schedule_sequence 通过读取进度计划日期本身所表明的顺序，补全缺失的逻辑关系——计划人员正确安排了工作，却没有建立任务链接，而这一决定可以还原。schedule_learn 从已完成的进度计划中挖掘每项活动的实际工期，以及通常的前置活动；schedule_generate 将这些信息转化为初稿，每套公寓或每层楼安排一项任务，并按历史记录所示的工种衔接顺序排列。

除了进度计划，向 schedule_learn 提供一份模型导出文件，它还会通过匹配共享代码，将工程量与任务关联起来，测算生产率——施工队每天实际完成的工作量。随后，schedule_generate 会根据新项目的工程量来确定工期，而不是照搬已记录的工期，因为项目之间可沿用的是效率，而会变化的是工程量。每个进度计划提供一份导出文件，并保持相同顺序：生产率按项目测算，跨项目汇总工程量会导致每个项目的数值都被放大。

初稿的排序质量取决于用于学习的进度计划。若源数据只将各项活动与自身逐个关联，却从未关联到周边工种，这两个工具都会指出这一情况并给出数量：知识库会报告学习到的前置活动并非活动自身的活动数量，初稿会报告排在任何工作之前、没有安排任务的工种数量。

项目控制 — schedule_risk，以及上述工具中的 PMO 相关功能

• 定量进度风险（schedule_risk）：基于网络自身逻辑进行蒙特卡洛模拟，涵盖全部四种链接类型和时滞；每项任务可设置三点估算范围，也可使用默认浮动范围。模拟按项目日历中的工作小时计数（包括半天星期六和经过时间时滞），并以进度计划自身的完工日期为基准，因此最可能的运行结果就是该进度计划。提供 P10/P50/P80/P90 完工日期、达到目标和基线的概率、P80 应急储备、按关键性和敏感度排列的风险驱动因素。使用固定种子的运行可完全复现。
• 周期状态报告（schedule_analyze 的 status_report aspect）：计划值与挣值、SPI、CPI、挣值进度 SPI(t)、三种方法计算的完工估算（EAC）、TCPI、预测完工日期、风险里程碑、主要问题，以及每个已记录截止日期的趋势。
• 成本加载型进度计划（schedule_update 的 load_budget op）：按代码加载预算，将相同的代码 BIM 链接到任务，并将成本分摊到任务；未分配给任何任务的项目会列出。timephased_query 的 s_curve measure 会返回累计 PV、EV 和 AC；加载成本后，数据以货币表示。
• 集成变更控制：重新设定基线时必须填写 reason（并记录 approvedBy）；每次基线设定、预算加载和已提交的编辑批次都会记录其对完工日期的影响（change_log aspect）。
• 短周期规划（lookahead aspect）：列出未来几周的工作及每项任务的约束、就绪或受约束状态，以及与上周记录承诺相比的 PPC（最后计划者系统）。
• WBS 规范：schedule_qa 检查 100% 规则（空汇总任务、汇总任务上的成本或资源、重复的 WBS 代码、只有一个子任务的汇总任务）；project_export 的 wbs_dictionary format 会生成 WBS 字典。

历史记录（截止日期、承诺、变更）保存在进度计划旁边的 <name>.hzpmo.json 中，因此无论哪个工具写入 .mpp 文件，历史记录都会保留。

互操作——project_export · project_import · bim_link · bim_sync

支持 CSV、JSON、MSPDI、Primavera XER 和 PMXML、本机 .mpp，以及经过整理的 Power BI 数据集。导入会先规划，再写入。

加载后需要多少开销

这 27 个工具在每次提示词中约占 13,500 个 token，只要服务保持连接就会一直如此。这是使用这些工具的实际代价，选择使用前值得了解。这也是工具数量维持在 25 个左右的原因：规模最大的替代方案提供 79 个工具，超过一定数量后，Agent 就难以在脑中掌握这些工具，从而无法在其中正确选择。

---

两项约定

未经验证，不会应用任何更改。

{
  "applied": 12,              // operations that fully succeeded, re-read from the model
  "fieldsVerified": 31,
  "rejected": [{
    "uid": 45, "field": "finish",
    "requested": "2026-09-10", "actual": "2026-09-14",
    "reason": "'finish' is calculated from the task's duration and its predecessors. Change the
               duration or the logic, or set a constraint, rather than writing the date."
  }],
  "impact": {
    "tasksMoved": 312,
    "projectFinishBefore": "2027-03-14", "projectFinishAfter": "2027-03-28",
    "criticalPathChanged": true, "newNegativeFloat": 8
  },
  "verifiedBy": "reread"
}

试运行是真正的模拟。 dryRun: true 会深度复制进度计划，应用批次，使用关键路径引擎重新排程，测量差异，然后丢弃副本。影响数据来自实际观测，而非预测。

---

如实说明功能

project_health 会公布功能矩阵，工具也会遵循该矩阵。文件后端上的两项功能仍为 false，并且会拒绝操作，而不是进行近似处理：

• write_native_mpp — 没有任何库能够编写这种二进制格式。如果已安装 Microsoft Project，保存操作会委托给它，并生成真正的 .mpp 文件；如果未安装，则会生成 MSPDI 并说明原因。
• level_resources — Microsoft Project 的资源平衡启发式算法未公开。任何仿制实现都会得出不同的结果，却冒用相同的名称。

如果基线中已有数据，除非明确要求，否则也会拒绝覆盖保存。基线记录的是原始计划，所有偏差都以此为衡量依据；一旦从文件中删除，就无法恢复。

其他所有功能——排程、重新计算、试运行模拟、未完成工作的重新排程、DCMA 关键路径测试——都可在任何环境中运行。由谁计算日期，详见下一节。

日期：由 Microsoft Project 自行计算

安装了 Microsoft Project 时，日期由 Microsoft Project 计算。 重新计算、写入后重新排程、试运行、恢复选项、目标日期和 DCMA 关键路径测试，都会将进度计划交给 Project，让它进行计算，再取回它计算出的日期。 project_health 会将其报告为 schedulingEngine: microsoft-project。

经过实测，而非假设。在 7 个真实的建筑进度计划中——包含汇总任务时，共有 21 至 5,984 个任务，总计 8,823 个任务，涵盖拆分任务、正在进行的工作、每天 9 小时以及周六半天工作——通过此服务重新计算后，每个进度计划中的每项任务，其日期都与 Microsoft Project 计算的结果精确到分钟一致，进度也与 Project 中的完全相同。写入操作同样遵循这一标准：通过此服务更改工期、完成百分比或新增链接，与在 Project 中手动进行相同编辑，得到的日期和进度都完全一致，逐项任务如此，汇总任务也不例外。

这不只是用 Project 打开文件就能做到的。Project 自带的 XML 导入功能并不能复现 Project 的结果：在一个真实的 126 个任务的进度计划中，即使重新打开 Project 自己导出的 XML，每项任务的日期也都变了。以下是造成差异的原因，以及交由 Project 处理时针对每种情况的做法：

• 未分配资源的任务。 没有资源的任务仍会带有一个占位分配，导入时 Project 会根据占位资源的日历而不是任务自身的日历进行排程。若占位分配没有提供任务本身未包含的信息，就会将其省略。
• 拆分任务。 工作开始、暂停再恢复时，间隔只保存在分配的逐日工作量中，因此这些信息也会一并传递。
• 正在进行的工作。 正在进行的任务经 XML 导入后，已完成工作中的一部分会被移入剩余工作。因此，绝不会从这次往返中取回进度；写入操作更改进度时，会遵循 Project 自己的规则——延长工期会保留已完成的工作，设置新的完成百分比会启动或完成任务——汇总任务也会像 Project 那样汇总。
• 空白行。 在 Project 中插入但保持为空的行，对 Project 来说不是任务，但读取时却会被视为一个日期为项目开始日期的任务，导致真实进度计划中的汇总任务为了包含它而向前延伸两年。传递时会保留为空白行。

重新计算包含 4,753 个任务的进度计划大约需要 20 秒，其中大部分时间耗在 Project 内部。

如果你已打开 Project，就会直接使用它。Microsoft Project 是单实例程序——任何自动化操作，包括此服务，都会在你正在使用的那个副本中执行——因此此服务绝不会隐藏你的窗口、重新计算或关闭你的文档，也只会操作它自己打开的临时副本，并在每个步骤之前确认当前活动文档仍是该副本。操作完成后，你仍停留在之前活动的文档中。

没有 Microsoft Project 时

MPXJ 能读取和写入进度计划文件，但不会对其进行排程，因此我们还提供了自己的关键路径引擎——正向和反向遍历、总浮时和自由浮时、全部 4 种关系类型、时差、约束、截止日期、实际日期，以及每项任务的工作日历。macOS、Linux 和未安装 Project 的 Windows 计算机上运行的就是这个引擎。

⚠️ 该引擎并非 Microsoft Project 的排程器

对于通过此服务创建的进度计划，它能精确复现 Project 的结果，但对真实导入的进度计划则不然：在 4 个生产文件中，它与 Project 自身的开始日期相符的任务比例分别为 100%、69%、23% 和 23%。它不支持任务类型、按投入量驱动的排程、由资源决定的日期、手动任务或拆分任务，也不支持经过的工期。因此，没有 Project 时，导入的进度计划绝不会在不知情的情况下被重新排程——它的日期会保持 Project 原有的日期，除非你明确要求使用此引擎，执行 schedule_update op='recalculate'，届时会先显示警告。读取、分析、DCMA-14 和挣值计算都使用文件中已有的日期，不受影响。

---

将其接入其他客户端

docs/INSTALL.md 中介绍了 Claude Desktop、Claude Code 和 Codex。对于其他通过 stdio 使用 MCP 的客户端——Cursor、VS Code 或你自己的客户端：

{
  "mcpServers": {
    "horizun-msproject": {
      "command": "horizun-msproject-mcp"
    }
  }
}

注册表名称：io.github.HorizunGroup/horizun-msproject-mcp（参见 .mcp/server.json）。

每次会话都先调用 project_health——它会告诉你当前使用的后端以及它能做什么。

从源代码构建和测试

cd src/HorizunMsProjectMcp && dotnet build && cd ../..
python tools/acceptance-test.py   # 65 checks, all tools end to end
python tools/scheduler-test.py    # 45 checks, critical-path engine correctness
python tools/planning-test.py     # 52 checks, reprogramming and learning
python tools/robustness-test.py   # 34 checks, concurrency and hostile input
python tools/smoke-test.py        # 15 checks, environment and capabilities
python tools/packaging-test.py    # 33 checks, the metadata every client reads
python tools/imported-file-test.py   # 16 checks, building on a file Project saved
python tools/planner-features-test.py  # 32 checks, calendars, costs, outline, scenarios, read-only safety
python tools/project-engine-test.py  # 29 checks, Microsoft Project as the engine (needs Project)

在 Windows 和 Linux 上，针对运行中的服务执行真实 JSON-RPC，共有 321 项检查。安装 Microsoft Project 后，测试套件会使用 Project 计算日期；project-engine-test.py 会逐项比较服务与 Project 手动执行同一操作的结果——任务日期、进度和汇总，并检查已打开的 Project 是否保持原样。Linux 任务则是最有力的证明：它在没有 JVM 和 Microsoft Project 的机器上运行。

验收测试套件会从零开始构建一份施工进度计划，并验证上述约定：试运行不会提交任何内容，循环依赖会在应用前被拒绝，写入未知 uid 会被拒绝而非忽略，DCMA 关键路径测试会使完成日期恰好推迟所注入的延迟时长。

调度器测试套件是建立日期可信度的关键。它覆盖开始到开始、完成到完成和开始到完成逻辑，正负时差，硬性和软性约束，产生负时差的截止日期，确实会推迟进度计划的日历例外，以及带汇总滚动的 WBS 层级；还验证导入的进度计划绝不会被静默重新排程，并对 Primavera XER 和 PMXML 进行完整往返测试，以及对真实二进制 .mpp 文件进行完整往返测试——该文件由 Microsoft Project 本身写入，再由 MPXJ 读回，日期、里程碑标志、预算代码和依赖关系均完好无损。

除测试套件外，服务还在两份生产环境中的施工进度计划上完成了规划人员的完整工作周期：一份包含 5,985 项任务，另一份大小为 170 MB、包含 1,937 项任务。整个过程包括打开、审计、建立基准、记录进度、衡量挣值、导出 Power BI 数据集，并读取多达 7,000 项任务的文件。

健壮性测试套件对于在真实客户端中放心使用至关重要：针对同一文档同时进行 40 次写入、恶意路径、荒谬的分页大小、非拉丁字符名称。MPXJ 的对象模型不是线程安全的，而 MCP 客户端可以自由地流水线调用——未加保护时，60 个并发写入全部失败，并导致文档无法使用。现在每份文档都有自己的锁；由于多个工具基于其他工具构建，因此锁可重入。

进度计划会一直保留在内存中，直到关闭；一份 170 MB 的文件约占用 400 MB。读取多份文件时，会淘汰最早打开且没有未保存更改的文档；如果所有已打开文档都有未保存的工作，则会拒绝再打开其他文档，而不是丢弃任何内容。project_health 会报告当前打开的文档及其资源占用。

使用 dotnet pack -c Release 重新构建可安装的软件包。

---

格式

读取 .mpp .mpt .mpx MSPDI .xml · Primavera .xer .pmxml · Asta .pp · Planner · GanttProject 等，依托 MPXJ 实现。

写入 MSPDI .xml（Microsoft Project 可原生打开）· .mpx · Primavera .xer 和 .pmxml · Planner · SDEF · JSON · CSV · Power BI 数据集 · 在安装了 Microsoft Project 的情况下写入原生 .mpp。

目录结构

src/HorizunMsProjectMcp/
  Diagnostics/   COM detection and the environment doctor
  Backends/      MPXJ I/O, the COM bridge, sessions and fingerprints
  Analysis/      critical-path engine, working calendar, DCMA-14, earned value
  Writes/        the verified-write engine
  Bim/           element matching and the 4D bridge
  Tools/         the 27 MCP tools
tools/
  acceptance-test.py   end-to-end across all tools, 65 checks
  scheduler-test.py    engine correctness, format round trips, safety guards, 45 checks
  planning-test.py     recovery, sequencing, target dates, learning, generation, 52 checks
  robustness-test.py   concurrency, malformed input, resource limits, 34 checks
  smoke-test.py        environment and capability matrix, 15 checks
  packaging-test.py    versions, identifiers and client manifests agree, 33 checks
  imported-file-test.py   a schedule Microsoft Project saved: ids, outline, custom fields, capacity, 16 checks
  planner-features-test.py  calendars, costs, outline, scenarios, S-curve, read-only safety, 32 checks
  project-engine-test.py  Microsoft Project as the engine, against Project by hand, 29 checks

设计原理及其背后的市场基准：DESIGN-TOOL-SURFACE.md 和 BENCHMARK-MCP-MSPROJECT.md。

学会指挥它

Horizun Hub 用西班牙语讲授如何在真实的施工和设计工作中指挥 AI Agent，以及如何在签字前审核它们交付的成果。这个 MCP 的课程是在 Microsoft Project 中运行 Agent：围绕真实施工工作的短课，并提供可验证的证书。

刚接触 Agent？注册账号即可免费学习从零开始运行 AI Agent的第 1 级。

许可证

MIT。