openproject-ce-mcp

# OpenProject 社区版 MCP [](https://pypi.org/project/openproject-ce-mcp/) [](https://www.python.org/downloads/) [](LICENSE) [](https://modelcontextprotocol.io) <p align="center"> <img src="img/openproject-ce-mcp-hero.jpg" alt="Hero image showing a Python terminal and an OpenProject board connected by a structured data stream." width="960"> </p> 一个适用于 OpenProject 的 MCP 服务器，允许本地 AI 代理通过结构化和受限的工具读取和管理项目数据。 服务器作为 MCP 客户端的标准输入输出子进程运行。它封装了 OpenProject API v3，并为项目、工作包、成员资格、版本、看板、时间条目等提供了类型化的工具。 --- ## 范围：社区版 该 MCP 服务器仅针对 **OpenProject 社区版**。它不支持企业版功能，例如： - 占位用户 - 预算 - 投资组合 - 程序 - 自定义操作 - 基线比较 **注意：** OpenProject 企业版包含其自己的 MCP 服务器。如果您拥有企业许可证，请使用官方企业 MCP 而不是此 MCP。 --- ## 目录 - [您可以执行的操作](#您可以执行的操作) - [工作原理](#工作原理) - [快速入门](#快速入门) - [配置](#配置) - [工具](#工具) - [集成](#集成) - [架构](#架构) - [开发](#开发) --- ## 您可以执行的操作 **项目** - 列出、创建、复制、更新和删除项目 - 读取项目配置、生命周期阶段和管理上下文 - 创建、更新和删除成员资格和版本；列出角色 **工作包** - 使用结构化筛选器列出和搜索工作包 - 创建、更新和删除工作包；创建子任务；创建、更新和删除关联；添加评论（不允许编辑或删除） - 上传和删除附件；添加和删除观察者；读取活动日志 - 记录、更新和删除时间条目 **看板和视图** - 创建、读取、更新和删除已保存的看板（查询）；读取视图 **用户和组** - 读取用户账户和组成员资格 - 创建、更新、锁定、解锁和删除用户；添加和删除组成员 **支持数据** - 按 ID 获取单个 Wiki 页面；创建、更新和删除新闻；读取和更新文档 - 读取和标记通知；读取帮助文本、工作日和实例配置 - 创建和检查网格；检查自定义选项 所有写入操作默认遵循先预览后确认的模式：首先调用一个工具获取验证的预览，然后再次调用并设置 `confirm=true` 以执行。可以通过设置 `OPENPROJECT_AUTO_CONFIRM_WRITE=true` 来全局禁用此行为。 --- ## 工作原理 - 通过标准输入输出与 MCP 客户端通信 — 无需远程服务器，无需持久存储 - 读取操作默认启用；写入操作需要通过环境变量显式启用 - 创建和更新操作在写入前会根据 OpenProject 表单端点验证有效载荷；删除和其他简单操作在确认后直接执行 - 服务器端强制执行项目范围：MCP 只会暴露配置的允许列表所允许的内容 - 响应是有界限和分页的 — 紧凑的摘要，而不是原始的 HAL 有效载荷 --- ## 快速入门 简而言之： 1. **安装服务器** （下面的单行命令）。 2. **复制 `command` 和 `env`** 到生成的 `.mcp.json` 文件中，并将其放入 MCP 客户端的配置中 — 或者让安装程序为您注册检测到的客户端。 3. **重启客户端**。 4. **验证**，通过调用 `list_projects` 进行测试。 本节的其余部分将详细介绍每个步骤。 ### 要求 | | | |---|---| | Python | 3.10 或更高版本 | | git | 仅在从源代码安装时需要（克隆此存储库） | | OpenProject | 社区版 16.1 或更高版本（已审查到 17.5 版本的兼容性），API v3 可访问 | | 操作系统 | macOS 12+、Linux 或 Windows 10/11 | 建议使用 [`uv`](https://github.com/astral-sh/uv) 进行依赖管理，但不是必需的。 ### 准备您的 OpenProject 实例 管理员必须启用 API 令牌创建： **管理 → API 和 Webhooks → API** | 设置 | 推荐 | |---|---| | 启用 API 令牌 | 选中 | | 只读属性的写入访问权限 | 未选中 | | 启用 CORS | 未选中 | 要创建个人令牌：**我的账户 → 访问令牌 → + API 令牌**。复制令牌立即 — 它只显示一次。格式：`opapi-...`。 ### 安装 从 PyPI 安装，然后运行交互式设置。选择您已经使用的安装程序： ```bash # uv（推荐）- 将 openproject-ce-mcp 命令安装到您的 PATH uv tool install openproject-ce-mcp # 或 pipx pipx install openproject-ce-mcp # 或 pip pip install openproject-ce-mcp ``` 然后配置它 — 这将收集您的 OpenProject URL/令牌和权限，并写入配置： ```bash openproject-ce-mcp configure ``` 它会询问两个独立的问题： 1. **全局配置（用户范围）？** — 在检测到的客户端的用户范围配置中注册服务器（例如 `~/.claude.json`），在每个项目中都可用。 2. **项目范围配置（当前目录）？** — 在当前目录中为每个受支持的客户端写入配置文件（`.mcp.json`、`.codex/config.toml`、`.vscode/mcp.json`、`.cursor/mcp.json`）；为每个受支持的客户端提供，即使未检测到。还会写入一个通用的 `.mcp.json` 文件，您可以从中复制值（除非您选择了 Claude Code，其项目配置就是 `.mcp.json`）。 选择一个或两个；选择都不将中止而不写入任何内容（在它询问您的令牌之前）。现有的其他 MCP 服务器的条目将被保留，并且每个编辑文件都将首先备份。写入后，它将告诉您如何（重新）加载每个客户端，以便服务器实际启动。 > **零安装运行：** 使用 `uv`，您可以完全跳过安装 — 将客户端的 `command` 指向 `uvx`，并使用参数 `["openproject-ce-mcp"]`。请参阅下面的客户端指南。 <details> <summary><b>替代：从源代码安装</b> （curl 一行命令，需要 git）</summary> 源代码安装程序克隆存储库，安装依赖项（如果有 `uv`，则使用 `uv`，否则使用 `venv` + `pip`），并运行相同的交互式设置。 **Windows（PowerShell）** — 克隆到 `%USERPROFILE%\openproject-ce-mcp`，二进制文件位于 `...\venv\Scripts\openproject-ce-mcp.exe`；设置 `$env:DIR` 以覆盖目标： ```powershell irm https://raw.githubusercontent.com/jtauschl/openproject-ce-mcp/main/get.ps1 | iex ``` **macOS / Linux** — 克隆到 `~/openproject-ce-mcp`，二进制文件位于 `~/openproject-ce-mcp/.venv/bin/openproject-ce-mcp`；`DIR=…` 覆盖目标： ```bash curl -fsSL https://raw.githubusercontent.com/jtauschl/openproject-ce-mcp/main/get.sh | sh ``` </details> PyPI/源代码安装在安装后使用相同的设置流程：项目目录获得一个本地的 `.mcp.json`；全局设置直接注册检测到的客户端（参见下文）。 ### 在 MCP 客户端中注册服务器 设置分为两个步骤： 1. **安装服务器一次** — `uv tool install` / `pipx` / `pip` 将 `openproject-ce-mcp` 命令放入您的 PATH（源代码安装在 `.venv` 中构建），无论您使用多少个客户端或项目。 2. **为每个客户端注册** — 每个客户端都需要一个单独的配置文件，指向该命令。注册仅指向已安装的命令；它不是第二次安装。使用多个客户端（例如 Claude *和* Codex）？为每个客户端创建一个配置文件；它们并排放置。 **我使用哪个指南？** 使用 VS Code → GitHub Copilot 指南。使用 Claude Code → Claude 指南。使用 Claude 桌面应用程序 → Claude Desktop 指南。使用 Cursor 或 Codex → 它们自己的指南。任何其他 MCP 客户端 → 通用说明如下。 文件、位置和格式因客户端而异；您不能逐字复制一个客户端的配置到另一个客户端： | 客户端 | 项目范围文件 | 用户范围文件 | 格式 | 根键 | |---|---|---|---|---| | Claude / Claude Code | `.mcp.json` | `~/.claude.json` | JSON | `mcpServers` | | Claude 桌面应用程序 | — （仅全局） | `claude_desktop_config.json` | JSON | `mcpServers` | | Codex | `.codex/config.toml` | `~/.codex/config.toml` | TOML | `[mcp_servers.openproject]` | | Cursor | `.cursor/mcp.json` | `~/.cursor/mcp.json` | JSON | `mcpServers` | | VS Code（GitHub Copilot） | `.vscode/mcp.json` | 用户 `mcp.json` | JSON | `servers` | > **VS Code 用户：** Copilot 指南是您的指南 — VS Code 通过 GitHub Copilot 在 Agent 模式下运行 MCP 服务器。 **`openproject-ce-mcp configure` 可以为您编写这些文件。** 在收集您的设置之前，它会询问两个独立的问题： - **全局配置（用户范围）？** — 将服务器添加到检测到的客户端的用户范围配置中，在每个项目中都可用。 - **项目范围配置（当前目录）？** — 在当前目录中为每个受支持的客户端写入配置文件，以及一个通用的 `.mcp.json` 文件，您可以从中复制值。 选择一个或两个；选择都不将中止而不写入任何内容。只有 `openproject` 条目被写入；其他 MCP 服务器的现有条目将被保留，并且每个编辑文件都将首先备份。 要手动注册，请从生成的 `.mcp.json` 中复制 `command` 和 `env` 值到文件中，并使用客户端指南显示的格式 — 值在客户端之间相同。 按照客户端指南： - [Claude / Claude Code](docs/claude.md) - [Claude 桌面应用程序](docs/claude-desktop.md) - [Codex](docs/codex.md) - [Cursor](docs/cursor.md) - [VS Code / GitHub Copilot](docs/github.md) **任何其他 MCP 客户端** （Windsurf、JetBrains AI Assistant/Junie、Cline、Continue、Warp、Zed、…）使用相同的模式：将 `command` 指向生成的 `.mcp.json` 中的二进制文件，并复制 `env` 值。根键几乎总是 `mcpServers`（Zed 使用 `context_servers`，带有 `"source": "custom"`；Continue 使用带有相同字段的 YAML）。 每个指南都显示了项目范围和/或用户范围的配置、如何重新加载客户端以及如何验证服务器被选中。 ### 故障排除 | 症状 | 可能的原因和解决方法 | |---|---| | 服务器/工具不出现 | 客户端未重新启动，或配置在错误的文件中。重新加载客户端并确认文件、位置和根键与上表中的行匹配。 | | 调用时出现 `[auth_error]` | `OPENPROJECT_API_TOKEN` 或 `OPENPROJECT_BASE_URL` 错误。重新检查两者；令牌为 `opapi-…`，基本 URL 没有尾随 `/api/v3`。 | | 工具出现但写入失败 | 写入是可选的。启用相关的 `OPENPROJECT_ENABLE_*_WRITE` 标志，并确保项目在 `OPENPROJECT_ALLOWED_PROJECTS_WRITE` 中。 | **卸载** 首先注销服务器。这会从客户端的 **用户范围** 配置文件和 **项目本地** 配置文件（当前目录中的 `.mcp.json`、`.codex/config.toml`、`.vscode/mcp.json`、`.cursor/mcp.json`）中删除 `openproject` 条目 — 因此，请从项目目录运行它以清理该目录。您的其他 MCP 服务器和设置将被保留，并且每个编辑文件都将首先备份。结果按范围分组： ```bash openproject-ce-mcp configure --uninstall # 或：openproject-ce-mcp-setup --uninstall ``` 然后删除您安装时匹配的包： ```bash uv tool uninstall openproject-ce-mcp # 或：pipx uninstall openproject-ce-mcp # 或：pip uninstall openproject-ce-mcp ``` <details> <summary><b>卸载源代码安装</b></summary> 如果您从源代码安装，`uninstall.sh` / `uninstall.ps1` 还会在注销客户端条目后删除本地环境（`.venv`、缓存、API 源代码克隆）： - **Windows:** `.\uninstall.ps1` （然后删除安装目录，如果需要：`Remove-Item -Recurse -Force $env:USERPROFILE\openproject-ce-mcp`） - **macOS / Linux:** `~/openproject-ce-mcp/uninstall.sh` </details> --- ## 配置 您的客户端配置文件（`.mcp.json`、`.codex/config.toml` 或 `.vscode/mcp.json`）包含您的 API 令牌。请像密码一样保护它。本存储库忽略 `.mcp.json`，但当您将项目范围的配置文件放在您自己的项目中时，请将其添加到该项目的 `.gitignore` 中，以免令牌被提交。 访问分为五个链：`project`、`membership`、`work_package`、`version` 和 `board`。每个链都有一个读取标志和一个写入标志。作用域标志独立控制每个链。 | 变量 | 必需 | 默认值 | 描述 | |---|---|---|---| | `OPENPROJECT_BASE_URL` | 是 | — | 您的 OpenProject 实例的基本 URL，例如 `https://op.example.com` | | `OPENPROJECT_API_TOKEN` | 是 | — | 个人 API 令牌 | | `OPENPROJECT_ALLOWED_PROJECTS_READ` | 否 | `*` | 可读项目；以逗号分隔的标识符、名称或通配符模式（例如 `my-project,team-*`）；`*` 允许所有可见项目 | | `OPENPROJECT_ALLOWED_PROJECTS_WRITE` | 否 | 空 | 可写项目；空禁用所有项目范围的写入；始终与读取范围相交 | | `OPENPROJECT_ALLOWED_PROJECTS` | 否 | — | `OPENPROJECT_ALLOWED_PROJECTS_READ` 的向后兼容别名 | | `OPENPROJECT_ENABLE_PROJECT_READ` | 否 | `true` | 项目、文档、新闻、Wiki、生命周期 | | `OPENPROJECT_ENABLE_WORK_PACKAGE_READ` | 否 | `true` | 工作包、关联、附件、时间条目 | | `OPENPROJECT_ENABLE_MEMBERSHIP_READ` | 否 | `true` | 成员资格、角色、主体 | | `OPENPROJECT_ENABLE_VERSION_READ` | 否 | `true` | 版本 | | `OPENPROJECT_ENABLE_BOARD_READ` | 否 | `true` | 看板和视图 | | `OPENPROJECT_HIDE_<ENTITY>_FIELDS` | 否 | 空 | 从读取中省略的逗号分隔字段，在写入时拒绝；支持 `*` 通配符 | | `OPENPROJECT_HIDE_CUSTOM_FIELDS` | 否 | 空 | 要省略的自定义字段名称或键；支持 `*` 通配符 | | `OPENPROJECT_ENABLE_ADMIN_WRITE` | 否 | `false` | 用户和组管理（创建/更新/删除/锁定用户，创建/更新/删除组）。必须显式设置 — 不由任何其他写入标志激活，也不会被 `openproject-ce-mcp configure` 提示。 | | `OPENPROJECT_ENABLE_PROJECT_WRITE` | 否 | `false` | 项目创建/更新/删除、新闻、文档、网格 | | `OPENPROJECT_ENABLE_MEMBERSHIP_WRITE` | 否 | `false` | 项目成员创建/更新/删除 | | `OPENPROJECT_ENABLE_WORK_PACKAGE_WRITE` | 否 | `false` | 工作包创建/更新/删除、评论、关联、附件、时间条目 | | `OPENPROJECT_ENABLE_VERSION_WRITE` | 否 | `false` | 版本创建/更新/删除 | | `OPENPROJECT_ENABLE_BOARD_WRITE` | 否 | `false` | 看板创建/更新/删除 | | `OPENPROJECT_AUTO_CONFIRM_WRITE` | 否 | `false` | 跳过所有写入的预览步骤 | | `OPENPROJECT_AUTO_CONFIRM_DELETE` | 否 | 继承 `OPENPROJECT_AUTO_CONFIRM_WRITE` | 跳过删除的预览步骤 | | `OPENPROJECT_ATTACHMENT_ROOT` | 否 | 当前工作目录 | 附件上传被限制在其中的目录。禁止目录外的文件，并且即使在目录内也拒绝凭证/配置文件的 `.mcp.json`、`.env`、`.pem` 等文件，因此工具调用无法渗出本地机密 | | `OPENPROJECT_TIMEOUT` | 否 | `12` | 秒为单位的请求超时时间 | | `OPENPROJECT_VERIFY_SSL` | 否 | `true` | 验证 TLS 证书 | | `OPENPROJECT_DEFAULT_PAGE_SIZE` | 否 | `20` | 每页默认结果数 | | `OPENPROJECT_MAX_PAGE_SIZE` | 否 | `50` | 请求的最大结果数上限 | | `OPENPROJECT_MAX_RESULTS` | 否 | `100` | 工具返回的总结果数的上限 | | `OPENPROJECT_LOG_LEVEL` | 否 | `WARNING` | `CRITICAL`、`ERROR`、`WARNING` 或 `INFO` | `OPENPROJECT_HIDE_<ENTITY>_FIELDS` 支持的实体：`project`、`membership`、`role`、`principal`、`user`、`group`、`project_access`、`project_admin_context`、`project_configuration`、`action`、`capability`、`job_status`、`project_phase_definition`、`project_phase`、`view`、`query_filter`、`query_column`、`query_operator`、`query_sort_by`、`query_filter_instance_schema`、`document`、`news`、`wiki_page`、`category`、`attachment`、`time_entry_activity`、`time_entry`、`work_package`、`relation`、`activity`、`reminder`、`version`、`board`、`current_user`、`instance_configuration`。 **永远不要在聊天消息、截图或日志输出中分享您的 API 令牌**。如果令牌已被暴露，请立即在 **我的账户 → 访问令牌** 中撤销它，并创建一个新的令牌。 --- ## 工具 工具按区域分组：项目、成员资格、用户、组、工作包、版本、看板、时间条目、Wiki、新闻、文档、通知、网格等。 参见完整的 [工具参考](docs/tools.md)，了解每个工具的描述。 ### 错误 每个工具故障都带有稳定的、机器可读的类别作为错误消息的前缀，因此代理可以根据故障类型进行分支，而不是解析自由文本。类别如下： | 类别 | 含义 | |---|---| | `[validation_error]` | 请求前拒绝输入（修复参数并重试） | | `[auth_error]` | 身份验证失败（检查 API 令牌） | | `[permission_denied]` | 令牌缺乏权限或禁用写入范围 | | `[not_found]` | 资源不存在（或功能需要更新的 OpenProject） | | `[transport_error]` | 无法访问 OpenProject（暂时性 — 安全重试） | | `[server_error]` | OpenProject 返回意外失败 | | `[openproject_error]` | 任何其他 OpenProject 端失败 | 成功的写入预览不是错误 — 它们返回一个结构化结果，包含 `ready`、`requires_confirmation`、`validation_errors` 和人类可读的 `message`。 ## 集成 服务器通过标准输入输出进行通信，与任何MCP客户端兼容。客户端特定的设置指南可在 [`docs/`](docs/) 文件夹中找到。 --- ## 架构 五个文件，没有复杂的抽象： - `config.py` — 环境解析和安全的默认值 - `client.py` — HTTP访问、策略检查、HAL规范化、预览/确认写入 - `models.py` — 返回给MCP客户端的紧凑数据类 - `tools.py` — 验证的MCP工具处理程序 - `server.py` — FastMCP生命周期连接 `client.py`故意设计得较大：所有策略敏感的逻辑（读取门控、写入门控、项目范围、字段隐藏）都集中在一个地方，以便于审计。 有关请求流程详细信息和安全模型，请参见 [docs/architecture.md](docs/architecture.md)。 --- ## 开发 ### 设置 ```bash git clone https://github.com/jtauschl/openproject-ce-mcp.git cd openproject-ce-mcp # 选项A：uv（推荐） uv sync --dev # 选项B：venv + pip python3 -m venv .venv .venv/bin/pip install -e ".[dev]" ``` ### 运行测试 **单元测试** （无网络 - 对 `httpx` 模拟运行）： ```bash # uv uv run pytest # venv .venv/bin/python -m pytest ``` **集成测试** （需要一个在线的OpenProject实例）： ```bash OPENPROJECT_BASE_URL=https://op.example.com \ OPENPROJECT_API_TOKEN=opapi-... \ OPENPROJECT_TEST_PROJECT=mcp-test \ uv run pytest -m integration -v ``` `OPENPROJECT_TEST_PROJECT` 是用于写入测试的项目标识符（默认为 `mcp-test`）。集成测试从默认运行中排除（`-m 'not integration'`），必须显式选择。 对于跨OpenProject版本的本地、临时实例（其中API更改了（16.6经典版 + 17.4 displayId + 17.5语义/工作区）），请参见 [`docker/test/`](docker/test/) — `docker/test/up.sh` 启动并初始化它们，并打印环境块以运行针对每个实例的集成测试。要针对OpenProject源代码跨版本验证客户端的API假设，请参见 [`tools/api-check/`](tools/api-check/)。 ### 代码更改后 MCP服务器作为子进程运行。进行任何代码更改后，在更新的工具生效之前，请重启您的MCP客户端。 ### 发布 该软件包通过GitHub Actions使用 [trusted publishing](https://docs.pypi.org/trusted-publishers/) （OIDC - 无API令牌存储）发布到 [PyPI](https://pypi.org/project/openproject-ce-mcp/)。 推送 `vX.Y.Z` 标签会触发 `.github/workflows/publish.yml`，该工作流运行测试矩阵，构建sdist + wheel，并上传它们。每次推送和PR也会运行测试矩阵以及 `build` 作业（`uv build` + `uvx twine check dist/*`），因此软件包始终可构建。 要发布新版本： 1. Bump `version` 在 `pyproject.toml` 中并更新 `CHANGELOG.md`。 2. 在本地运行 `uv run pytest` 和 `uv build`（CI强制执行两者）。 3. 合并到 `main`，然后标记：`git tag vX.Y.Z && git push origin vX.Y.Z`。 4. `publish.yml` 工作流自动构建并上传到PyPI。 从标签创建GitHub发布以发布说明。