OpenProject MCP 服务器

一个高质量的 Model Context Protocol (MCP) 服务器，用于将 Claude 连接到你的 OpenProject 实例。它允许 Claude 直接在对话中查询、搜索和管理项目、工作包、用户和时间条目。

🚀 功能特性

✅ 项目访问 - 列出、筛选和获取项目详情
✅ 工作包管理 - 查看任务、缺陷、功能，支持高级筛选
✅ 全文搜索 - 按内容搜索工作包
✅ 活动历史 - 查看工作包的变更和评论
✅ 用户管理 - 列出和获取用户信息
✅ 时间条目 - 按项目、用户、时间段查询已记录的时间
✅ 智能分页 - 支持大型数据集
✅ 健壮的错误处理 - 清晰且可操作的消息
✅ 完整类型支持 - 使用 TypeScript 实现最大类型安全

Related MCP server: OpenProject MCP Server

📋 前提条件

• Node.js 18+ 或 Bun 1.0+

• 一个 OpenProject 13+ 实例，具有 API 访问权限

• 一个 OpenProject API 令牌（可在设置中生成）

🔧 安装

1. 克隆或下载服务器

cd openproject-mcp-server

2. 安装依赖

npm install
# o con bun
bun install

3. 配置环境变量

将 .env.example 复制为 .env 并填写值：

cp .env.example .env

编辑 .env：

OPENPROJECT_URL=https://openproject.empresa.com
OPENPROJECT_API_TOKEN=tu-token-api-aqui
OPENPROJECT_PAGE_SIZE=50

如何在 OpenProject 中生成 API 令牌：

1. 在 OpenProject 中，转到 管理 → API 和 Webhooks → 个人访问令牌

2. 点击 “+ 新建个人访问令牌”

3. 指定一个描述性名称（例如 “Claude MCP”）

4. 勾选所需权限：

   • ✅ view_work_packages

   • ✅ view_projects

   • ✅ view_users

   • ✅ view_time_entries

   • ✅ edit_work_packages（如果你想创建/编辑）

5. 将生成的令牌复制到 .env

4. 编译服务器

npm run build

🎯 使用方法

选项 A：在 Claude Code 中

1. 打开 Claude Code

2. 转到 设置 → MCP 服务器

3. 点击 + 添加本地服务器

4. 配置：

   • 名称：openproject

   • 命令：node

   • 参数：["path/to/openproject-mcp-server/dist/index.js"]

   • 环境变量：.env 中的值

5. 保存并重新连接到 Claude

选项 B：本地运行以进行测试

npm run dev

然后在另一个终端中，使用 MCP Inspector：

npm run inspect

这将打开一个 Web 界面，你可以在其中测试每个工具。

选项 C：在 Claude.ai 中

1. 打开 claude.ai/code

2. 转到 设置 → MCP 服务器

3. 如果你将此服务器部署在可访问的主机上，则添加一个远程服务器

4. 配置访问凭据

🛠️ 可用工具

📦 项目

list_projects

列出所有项目，支持可选筛选。

参数：

• offset（数字，可选）：用于分页

• name_filter（字符串，可选）：按名称筛选

• status（枚举："active" | "archived"，可选）：按状态筛选

示例：

Claude: List all active projects
→ OpenProject: Muestra proyectos activos

get_project

获取项目的完整详情。

参数：

• project_id（字符串 | 数字）：项目的 ID 或标识符

📋 工作包（任务）

list_work_packages

列出工作包，支持高级筛选。

参数：

• project_id（字符串 | 数字，可选）：按项目筛选

• status（字符串，可选）：状态（例如 “Open”、“In Progress”）

• priority（字符串，可选）：优先级

• assignee_id（数字，可选）：分配给用户

• search（字符串，可选）：文本搜索

• offset（数字，可选）：分页

get_work_package

获取工作包的完整详情。

参数：

• work_package_id（数字）：工作包的 ID

get_work_package_activities

获取变更和评论的历史记录。

参数：

• work_package_id（数字）：工作包的 ID

search_work_packages

在工作包中进行全文搜索。

参数：

• query（字符串，必填）：搜索词

• project_id（字符串 | 数字，可选）：限制到项目

• status（字符串，可选）：按状态筛选

• priority（字符串，可选）：按优先级筛选

👤 用户

list_users

列出 OpenProject 中的所有用户。

参数：

• offset（数字，可选）：分页

get_user

获取特定用户的详情。

参数：

• user_id（数字）：用户的 ID

⏱️ 时间条目

list_time_entries

列出时间条目，支持按时间段、用户、项目筛选。

参数：

• work_package_id（数字，可选）：按工作包筛选

• user_id（数字，可选）：按用户筛选

• project_id（字符串 | 数字，可选）：按项目筛选

• from_date（字符串，可选）：开始日期（YYYY-MM-DD）

• to_date（字符串，可选）：结束日期（YYYY-MM-DD）

• offset（数字，可选）：分页

get_time_entry

获取时间条目的详情。

参数：

• time_entry_id（数字）：时间条目的 ID

✍️ 写入（创建史诗和用户故事）

list_project_types

列出项目中可用的工作包类型（Epic、User Story、Task、Bug 等）及其 ID。请先使用此工具 — 类型 ID 因 OpenProject 实例而异。

参数：

• project_id（字符串 | 数字）：项目的 ID 或标识符

create_work_package

创建工作包（史诗、用户故事、任务等）。使用 parent_id 将用户故事挂在其史诗下。

参数：

• project_id（字符串 | 数字）

• subject（字符串）

• description（字符串，可选，Markdown）

• type_id（数字，可选）：类型 ID，通过 list_project_types 获取

• parent_id（数字，可选）：父史诗的 ID

• priority_id、assignee_id、start_date、due_date（可选）

create_work_packages_bulk

在一次调用中创建多个工作包（非常适合上传从 Word 中提取的所有用户故事）。每个项目可以有自己的 parent_id，因此来自不同史诗的故事可以在同一次调用中创建。返回每个项目的报告（成功/失败），如果某个失败，不会中止整个批次。

参数：

• project_id（字符串 | 数字）

• items（数组，最多 100 个）：每个项目具有与 create_work_package 相同的字段（不包括 project_id）

📋 流程：从 Word 上传史诗和用户故事

团队的典型用例：他们有以 .docx 编写的用户故事，需要将其加载到 OpenProject 中，并保持史诗 → 故事的关系。

1. 生成你的个人 API 令牌（每个开发人员使用自己的，见上文）并配置你的本地 .env。

2. 打开与 Claude 的对话，并附加或引用包含史诗/故事的 .docx 文件（Claude 可以直接读取）。

3. 要求 Claude：“阅读此 Word 文档，识别史诗及其用户故事，并将它们上传到 OpenProject 的项目 X”。

4. Claude 通常会执行以下操作，无需你手动编排：

   • 对项目调用 list_project_types 以获取 Epic 和 User Story 的 type_id。

   • 为每个史诗调用 create_work_package（数量少，逐个创建以获取其 ID）。

   • 为用户故事调用 create_work_packages_bulk，使用每个故事对应史诗的 parent_id。

5. 检查最终报告（创建了什么，什么失败），并在 OpenProject 中根据需要更正。

注意：令牌需要 edit_work_packages 权限（见令牌生成部分）才能创建，而不仅仅是读取。

📊 使用案例

1. 项目分析

Claude: "Análiza todos los proyectos activos y resume cuáles tienen más work packages abiertos"
→ El servidor lista proyectos, luego itera para contar paquetes abiertos

2. 任务搜索

Claude: "Busca todas las tareas sobre 'API' en estado 'In Progress' del proyecto BACKEND"
→ search_work_packages con query="API", status="In Progress", project_id="BACKEND"

3. 时间报告

Claude: "¿Cuántas horas registró Juan en la última semana?"
→ list_time_entries con user_id=juan, from_date=última_semana

4. 项目状态

Claude: "Dame un resumen del proyecto FRONTEND: qué se completó, qué está en progreso y qué sigue"
→ get_project + list_work_packages con diferentes status

5. 变更审计

Claude: "¿Quién cambió el estado del work package #123 y cuándo?"
→ get_work_package_activities para ver el historial

🏗️ 架构

src/
├── index.ts                 # Entry point del servidor MCP
├── client/
│   └── openproject.ts       # Cliente HTTP para OpenProject API
├── tools.ts                 # Registro e implementación de herramientas
├── schemas/
│   └── index.ts             # Validación Zod de inputs
└── utils/
    └── formatters.ts        # Formatos de salida Markdown

🔐 安全性

• ✅ Bearer 令牌认证（安全，不需要明文凭据）

• ✅ 使用 Zod 进行输入验证（防止注入）

• ✅ 细粒度的错误处理（不暴露敏感数据）

• ✅ TypeScript 严格模式（防止类型错误）

• ⚠️ 令牌存储在 .env 中 - 不要将此文件提交到 git

🚨 故障排除

“Authentication failed”

• 验证 .env 中的令牌是否有效

• 在 OpenProject 中重新生成新令牌

“Connection error”

• 验证 OPENPROJECT_URL 是否可从你的机器访问

• 如果使用代理/VPN，请配置代理环境变量

“No projects found”

• 验证你的用户是否有查看项目的权限

• 验证你的实例中是否存在项目

服务器无法启动

npm run build
npm run dev

检查终端中的错误输出。

📈 即将推出的改进

• 支持从 Claude 创建/编辑工作包

• 支持工作包评论

• 与甘特图集成

• 用于实时通知的 Webhooks

• 数据缓存以提高性能

• 全面评估（SEP）

📦 分发给你的开发团队

每个开发人员需要自己的副本 + 自己的 API 令牌（切勿在多人之间共享令牌 — 操作会在 OpenProject 中按用户审计）。

推荐选项：共享 Git 仓库

1. 将此文件夹上传到私有仓库（GitHub 组织或 linux.ie 的 Gitea/GitLab）。不要忘记 .env 已在 .gitignore 中 — 永远不会被上传。

2. 每个开发人员：

   git clone <url-del-repo>
   cd openproject-mcp-server
   npm install
   npm run build
   cp .env.example .env

3. 每个人生成自己的令牌（管理 → API 和 Webhooks → 个人访问令牌，如果他们要创建故事，则需要 edit_work_packages 权限）并将其粘贴到自己的 .env 中。

4. 每个人将其添加到 Claude Code（设置 → MCP 服务器 → 添加本地服务器），指向他们本地的 dist/index.js。

无 Git 的替代方案：压缩文件夹

如果你还不想设置仓库，可以共享文件夹的 .zip（排除 node_modules、dist 和 .env），并让每个开发人员本地执行 npm install && npm run build。机制相同，只是分发方式不同 — 不需要 CI/CD，因为没有要部署的中央服务器：MCP 在每个开发人员的机器上以 stdio 运行。

如果以后将其作为共享远程服务器运行

如果与其让每个开发人员本地运行，你更希望有一个单一服务器（例如在 linux.ie 上）供所有人使用，那么确实需要 CI/CD（每次推送时构建 + 部署），并且需要将传输方式从 stdio 迁移到 HTTP。这是一个更大的架构跳跃 — 如果这是你想要的路径，请告诉我，我们另行规划。

🤝 贡献

这是一个开源 MCP 服务器。要改进：

1. Fork 仓库

2. 为你的功能创建分支（git checkout -b feature/mi-feature）

3. 提交更改（git commit -am 'Agrego mi-feature'）

4. 推送到分支（git push origin feature/mi-feature）

5. 打开 Pull Request

📄 许可证

MIT - 随意使用、修改和分发

💬 支持

要报告错误、提问或提出建议：

• 在仓库中打开 issue

• 查阅 MCP 文档

• 查看 OpenProject API 文档

为 Integral de Empaques S.A.S. 用 ❤️ 制作