OpenProject CE

OpenProject CE MCP

适用于 OpenProject 的 MCP 服务，让本地 AI Agent 通过结构化且受控的工具读取和管理项目数据。

该服务通过 stdio 作为 MCP 客户端的本地子进程运行。它封装了 OpenProject API v3，并提供面向项目、工作包、成员关系、版本、看板、会议、时间条目等的类型化工具。

在 PyPI 上阅读本文？ 以下所有链接都指向 GitHub 仓库 — docs/ 页面和图片随 git 仓库和源代码发行包一起提供， 不包含在已安装的包中。

为什么使用此 MCP

• 专为节省上下文而设计 — 返回紧凑、适合 Agent 的响应，而非原始 HAL 负载（原始 API 中每个条目约有 21 个字段和 46 个链接）。使用 select 时，每个响应的 token 数最多可减少 −99%；完整数据请参阅上下文效率。
• 受控写入 — 每次写入都遵循先预览、再确认的模式；无法绕过。
• 纵深防御项目范围 — MCP 读取/写入允许列表会进一步限制令牌的有效范围，除此之外还受 OpenProject 自身的服务器端权限控制。
• 类型化工具，而非原始 REST 客户端 — 每种意图（列表、搜索、创建、更新）只需一次调用，无需手动构造 HAL 请求并跟进链接。

---

可执行的操作

项目

• 列出、创建、复制、更新和删除项目
• 读取项目配置、生命周期阶段和管理上下文
• 创建、更新和删除成员关系与版本；列出角色

工作包

• 使用结构化筛选条件列出和搜索工作包
• 创建、更新和删除工作包；创建子任务；创建、更新和删除关联；添加评论（不支持编辑或删除）
• 上传、读取（将图像和文本内联提供给模型）和删除附件；添加和移除关注者；读取活动日志
• 记录、更新和删除时间条目

看板和视图

• 创建、读取、更新和删除已保存的看板（查询）；读取视图

会议

• 创建、读取、更新和删除会议及其议程条目、分区和结果
• 管理定期会议：创建、更新和删除系列；列出会议场次；初始化或取消单个场次

管理和日程安排（可选启用）

• 读取用户账户和群组成员关系
• 创建、更新、锁定、解锁和删除用户；添加和移除群组成员
• 读取和管理文件存储连接（例如 Nextcloud）
• 读取和管理用户的非工作时间及工作时间

辅助数据

• 按 ID 获取单个 wiki 页面；创建、更新和删除新闻；读取和更新文档
• 读取和标记通知；读取帮助文本、工作日和实例配置
• 创建和检查网格；检查自定义选项

所有写入操作都遵循先预览、再确认的模式：先调用一次工具获取经过验证的预览，然后再次调用并设置 confirm=true 执行。无法绕过此流程。

---

范围：社区版

此 MCP 服务仅面向 OpenProject Community Edition。它不支持 Enterprise Edition 的功能，例如：

• 占位用户
• 投资组合
• 计划
• 自定义操作
• 基线比较

注意： OpenProject Enterprise Edition 自带 MCP 服务。如果你拥有 Enterprise 许可证，请使用官方 Enterprise MCP，而不是此服务。

---

工作原理

• 通过 stdio 与 MCP 客户端通信——没有远程服务，也没有持久化存储
• 核心读取类别（项目、工作包、成员资格、版本、看板、会议）默认启用，但在 OPENPROJECT_READ_PROJECTS 列出某个项目之前，只会注册 list_statuses、list_types 和 get_current_user 等与项目无关的工具。个人、管理员、用户日程和扩展元数据工具需选择启用
• 项目范围内的写入类别默认启用，但只有在 OPENPROJECT_READ_PROJECTS 和 OPENPROJECT_WRITE_PROJECTS 都列出某个项目时，才会注册对应工具；写入操作也只能作用于两者都列出的项目。真正起限制作用的是允许列表，而不是类别标志。个人数据、管理员和用户日程写入需选择启用
• 创建和更新操作会先根据 OpenProject 表单端点验证载荷，再执行写入；删除和其他简单操作则会在确认后直接执行
• 服务端会强制实施项目范围：MCP 只会公开配置的允许列表所允许的内容
• 响应有大小限制并采用分页——返回精简摘要，而不是原始 HAL 载荷

与直接调用 OpenProject REST API 相比，使用此 MCP 的一个核心原因是：它返回节省上下文的响应，而不仅限于列表操作。以下数据是对同一组具有代表性的三个工作包进行测量的结果（使用真实的 tiktoken 计数，而非按字节数除以 4 估算）；读取、搜索、写入和批量调用的结果都处于 −85% 至 −98% 的范围内。如需查看各调用类型的详细数据、工具目录大小数据以及复现方法，请参阅上下文效率。

响应	令牌数	相较于原始 API
原始 OpenProject REST API v3（HAL）	~9,992	基准
list_work_packages（MCP）	~861	−91%
带有 select（5 个字段）的 list_work_packages	~174	−98%

---

安装

此快速入门需要 pipx；如果尚未安装，请参阅安装指南。

pipx install openproject-ce-mcp
openproject-ce-mcp configure
openproject-ce-mcp --version

如果你已经在使用 uv，也可以用 uv tool install openproject-ce-mcp，效果相同。 如需了解何时适合使用普通的 pip install，以及如何使用 uvx（无需安装、按需运行的替代方式），请参阅安装指南。

configure 会收集你的 OpenProject URL、API 令牌和项目范围，然后为你选择的 MCP 客户端写入配置。建议使用项目范围：这样服务就只在当前项目中可用。全局范围则会使其在所有位置都可用。之后请重启 MCP 客户端，然后让它调用 get_current_user 或 list_projects 进行验证。

如需了解系统要求、更新、从源码安装和卸载，请参阅安装指南；如需查看各客户端的配置指南，请参阅客户端。

---

文档

完整文档位于 docs/，可从 文档中心开始浏览：

• 设置： 安装 · 客户端 · 配置 · 故障排除
• 使用工具： 工具参考 · 工作包筛选器 · 字段隐藏
• 客户端指南： Claude / Claude Code · Claude Desktop · Codex · Cursor · VS Code / GitHub Copilot
• 贡献： 开发 · 架构 · 上下文效率

---

配置要点

客户端配置（.mcp.json、.codex/config.toml 或 .vscode/mcp.json） 中包含 API 令牌——请像对待密码一样保护它，并避免将其纳入版本控制；要了解准确的 .gitignore 操作步骤，请从客户端中选择对应的客户端指南。configure 只会写入最简配置：仅包含与安全默认值不同的值。核心读取组和项目范围的写入类别默认已启用，但只有在 OPENPROJECT_READ_PROJECTS 中列出项目后，才会注册其项目范围工具并授予项目访问权限；对于写入，还必须在 OPENPROJECT_WRITE_PROJECTS 中列出项目。这对允许列表才是真正的限制，类别标志并非如此。

请参阅配置，了解完整的环境变量参考，以及 configure --quick 与 --advanced 各自会询问哪些内容。

---

安全性

提示词注入

用户提供的文本（工作包描述、评论、新闻、Wiki 内容）会用 <user-content> 标签标记，并在服务说明中标明为不可信内容。Agent 应将其视为数据，而非指令。

请参阅 SECURITY.md，了解完整的安全模型，包括提示词注入缓解措施、报告流程和支持的版本。

---

问题和错误报告

请在 GitHub Discussions 中提问。 请在 GitHub Issues 中报告错误并请求功能。 请按照 SECURITY.md 中的说明，私下报告安全漏洞。

---

开发

main 是最近一次发布的冻结快照，并非活跃开发分支。请参阅 CONTRIBUTING.md，了解应克隆哪个分支（活跃开发或错误修复）以及完整的测试套件（单元测试、集成测试和 Docker 测试实例）。

---

许可证

MIT — 详见 LICENSE。整个项目由一个顶层许可证文件涵盖；单个源文件不附带逐文件版权声明，这符合 MIT 许可 Python 包的常见做法。