OpenProject MCP

Name: OpenProject MCP
Author: AndyEverything

本地服务

github.com/AndyEverything生产力9133 周前更新

代码仓库

关于 OpenProject MCP

OpenProject MCP 是一个基于 FastMCP 框架的 MCP 服务，对接 OpenProject API v3，用于项目、工作包和类型的查询与创建。项目目前处于早期阶段，README 明确表示不建议用于生产环境。

主要功能

01列出与筛选项目
02按多种条件筛选工作包
03搜索工作包的主题或 ID
04列出工作包类型
05支持 API Key 认证与可选代理

适用场景

01查询指定项目中的高优先级或逾期工作包
02按主题或 ID 查找具体任务
03在 LLM 对话中获取项目与任务状态

MCP 相关

该项目是 MCP 服务，通过 stdio 或 SSE 方式向 MCP 客户端暴露 OpenProject 相关工具，README 中提到约 40 个以上工具。

#openproject #project #management

配置

本地服务的配置在各客户端中通用，复制后粘贴到客户端的 MCP 配置文件即可。

暂未收录安装方式

我们还没有获取到这个服务的安装包或远程地址，请按项目 README 中的说明安装。

代码仓库

工具

还没有获取到工具列表

本地服务需要在你的电脑上运行后才能读取工具，维护者暂未提供工具列表。

详细介绍

⚠️ 这是一个早期阶段的项目。请勿用于生产环境——欢迎贡献！

OpenProject MCP 服务

一种模型上下文协议（MCP）服务，可与 OpenProject API v3 无缝集成。此服务使大模型应用能够与 OpenProject 交互，以进行项目管理、工作包跟踪和任务创建。

功能

🔌 完整集成 OpenProject API v3
📋 项目管理：列出和筛选项目
📝 工作包管理：创建、列出和筛选工作包
🏷️ 类型管理：列出可用的工作包类型
🔐 安全认证：基于 API 密钥的身份验证
🌐 代理支持：可选的 HTTP 代理配置
🚀 异步操作：采用现代 async/await 模式构建
📊 全面的日志记录：可配置日志级别

前提条件

Python 3.10 或更高版本
uv（快速的 Python 包管理器）
一个 OpenProject 实例（云端或可自托管）
OpenProject API 密钥（从用户个人资料中生成）

安装

1. 安装 uv（如果尚未安装）

macOS/Linux：

curl -LsSf https://astral.sh/uv/install.sh | sh

Windows：

powershell -c "irm https://astral.sh/uv/install.ps1 | iex"

替代方式（使用 pip）：

pip install uv

2. 克隆并设置项目

git clone https://github.com/yourusername/openproject-mcp.git
cd openproject-mcp

3. 创建虚拟环境并安装依赖项

# Create virtual environment and install dependencies in one command
uv sync

替代方式（手动步骤）：

# Create virtual environment
uv venv

# Install dependencies
uv pip install -r requirements.txt

4. 配置环境

# Copy the environment template
cp env_example.txt .env

编辑 .env 并添加 OpenProject 配置：

OPENPROJECT_URL=https://your-instance.openproject.com
OPENPROJECT_API_KEY=your-api-key-here

配置

环境变量

变量	必需	描述	示例
`OPENPROJECT_URL`	是	OpenProject 实例的 URL	`https://mycompany.openproject.com`
`OPENPROJECT_API_KEY`	是	OpenProject 用户个人资料中的 API 密钥	`8169846b42461e6e...`
`OPENPROJECT_PROXY`	否	如有需要，填写 HTTP 代理 URL	`http://proxy.company.com:8080`
`LOG_LEVEL`	否	日志级别（DEBUG、INFO、WARNING、ERROR）	`INFO`
`TEST_CONNECTION_ON_STARTUP`	否	服务启动时测试 API 连接	`true`

获取 API 密钥

登录 OpenProject 实例
前往 My account（点击头像）
转到 Access tokens
点击 + Add 创建新令牌
为令牌命名并复制生成的令牌

使用方法

部署选项

此 MCP 服务可通过两种方式部署：

本地（stdio）：在本地计算机上运行，供个人使用
云端（SSE）：部署到 FastMCP Cloud，供团队或组织访问

选项 1：本地部署（stdio）

运行服务

使用 uv（推荐）：

uv run python openproject-mcp-fastmcp.py

替代方式（手动激活）：

# Activate virtual environment
source .venv/bin/activate  # On Windows: .venv\Scripts\activate

# Run the server
python openproject-mcp-fastmcp.py

文件结构：

openproject-mcp-fastmcp.py - Stdio 传输（适用于本地 Claude Desktop）
openproject-mcp-sse.py - SSE 传输（适用于 FastMCP Cloud）
src/ - 使用 FastMCP 框架实现的核心功能
- src/server.py - FastMCP 服务初始化
- src/client.py - OpenProject API 客户端
- src/tools/ - 按类别组织的全部 40 多个 MCP 工具

与 Claude Desktop 集成

通过 CLI 快速安装（推荐）：

此命令适用于 Claude Desktop 和 Claude Code (VSCode extension)。

# Windows - Replace <YOUR_PROJECT_PATH> with your actual path
claude mcp add openproject-fastmcp "<YOUR_PROJECT_PATH>\.venv\Scripts\python.exe" "<YOUR_PROJECT_PATH>\openproject-mcp-fastmcp.py" -e "PYTHONPATH=<YOUR_PROJECT_PATH>" -e "OPENPROJECT_URL=https://your-instance.com" -e "OPENPROJECT_API_KEY=your-api-key"

# macOS/Linux - Replace <YOUR_PROJECT_PATH> with your actual path
claude mcp add openproject-fastmcp "<YOUR_PROJECT_PATH>/.venv/bin/python" "<YOUR_PROJECT_PATH>/openproject-mcp-fastmcp.py" -e "PYTHONPATH=<YOUR_PROJECT_PATH>" -e "OPENPROJECT_URL=https://your-instance.com" -e "OPENPROJECT_API_KEY=your-api-key"

示例（Windows）：

# If you cloned the project to C:\Users\YourName\openproject-mcp-server
claude mcp add openproject-fastmcp "C:\Users\YourName\openproject-mcp-server\.venv\Scripts\python.exe" "C:\Users\YourName\openproject-mcp-server\openproject-mcp-fastmcp.py" -e "PYTHONPATH=C:\Users\YourName\openproject-mcp-server" -e "OPENPROJECT_URL=https://manage.example.com" -e "OPENPROJECT_API_KEY=abc123xyz456"

示例（macOS/Linux）：

# If you cloned the project to /home/yourname/openproject-mcp-server
claude mcp add openproject-fastmcp "/home/yourname/openproject-mcp-server/.venv/bin/python" "/home/yourname/openproject-mcp-server/openproject-mcp-fastmcp.py" -e "PYTHONPATH=/home/yourname/openproject-mcp-server" -e "OPENPROJECT_URL=https://manage.example.com" -e "OPENPROJECT_API_KEY=abc123xyz456"

**重要提示：**替换以下值：

将 <YOUR_PROJECT_PATH> 替换为实际安装目录
将 https://your-instance.com 替换为你的 OpenProject URL
将 your-api-key 替换为 Account Settings 中的 API 密钥

验证安装：

claude mcp list

你应该会看到：

openproject-fastmcp: ... - ✓ Connected

运行命令后，重启 Claude Desktop 或重新加载 VSCode 窗口。

手动配置：

将此配置添加到 Claude Desktop 配置文件中：

配置文件位置：

Windows：%APPDATA%\Claude\claude_desktop_config.json
macOS：~/Library/Application Support/Claude/claude_desktop_config.json
Linux：~/.config/Claude/claude_desktop_config.json

Windows 配置：

{
  "mcpServers": {
    "openproject-fastmcp": {
      "command": "D:\\Promete\\Project\\mcp-openproject\\openproject-mcp-server\\.venv\\Scripts\\python.exe",
      "args": ["D:\\Promete\\Project\\mcp-openproject\\openproject-mcp-server\\openproject-mcp-fastmcp.py"],
      "env": {
        "PYTHONPATH": "D:\\Promete\\Project\\mcp-openproject\\openproject-mcp-server",
        "OPENPROJECT_URL": "https://your-instance.com",
        "OPENPROJECT_API_KEY": "your-api-key"
      }
    }
  }
}

macOS/Linux 配置：

{
  "mcpServers": {
    "openproject-fastmcp": {
      "command": "/path/to/project/.venv/bin/python",
      "args": ["/path/to/project/openproject-mcp-fastmcp.py"],
      "env": {
        "PYTHONPATH": "/path/to/project",
        "OPENPROJECT_URL": "https://your-instance.com",
        "OPENPROJECT_API_KEY": "your-api-key"
      }
    }
  }
}

**注意：**在配置中使用环境变量比将凭据存储在 .env 文件中更安全。

验证：

检查服务是否已连接：

claude mcp list

你应该会看到：

openproject-fastmcp: ... - ✓ Connected

如果看到 ✗ Failed to connect，请检查：

Python 路径是否正确
openproject-mcp-fastmcp.py 文件是否存在
环境变量是否设置正确
配置更改后是否重启了 Claude Desktop

选项 2：云端部署（FastMCP Cloud）☁️

部署到 FastMCP Cloud，即可在整个组织中集中访问。这样，每位用户都无需安装 Python 并在本地运行服务。

优势：

最终用户无需本地安装
集中管理 API 密钥和配置
可从任何有互联网连接的地方访问
自动扩展和监控
团队协作功能

快速入门：

确保已有 SSE 入口点：

# The project includes openproject-mcp-sse.py for cloud deployment
ls openproject-mcp-sse.py

创建/更新 .fastmcp.yaml 配置：

name: openproject-mcp
version: "1.0.0"
description: "OpenProject MCP Server for Claude Desktop"

entry_point: openproject-mcp-sse.py

runtime:
  python_version: "3.11"

environment:
  - OPENPROJECT_URL
  - OPENPROJECT_API_KEY
  - OPENPROJECT_PROXY

部署到 FastMCP Cloud：

# Install FastMCP CLI (if not installed)
pip install fastmcp

# Login to FastMCP Cloud
fastmcp login

# Deploy your server
fastmcp deploy

在 FastMCP Cloud 控制面板上配置环境变量：
- OPENPROJECT_URL：你的 OpenProject 实例 URL
- OPENPROJECT_API_KEY：你的 API 密钥
- OPENPROJECT_PROXY：（可选）需要时填写代理 URL

用户通过 Claude Desktop 使用 SSE 传输连接：

{
  "mcpServers": {
    "openproject": {
      "url": "https://mcp.fastmcp.com/sse/openproject-mcp",
      "transport": "sse"
    }
  }
}

📚 详细文档：

快速入门指南 - 5 分钟快速设置
FastMCP Cloud 部署指南（英文） - 全面指南
Hướng dẫn kết nối Cloud (Tiếng Việt) - 越南语指南

有关全面的部署说明、故障排除和最佳实践，请参阅上述指南。

可用工具

1. `test_connection`

测试与 OpenProject 实例的连接。

示例：

Test the OpenProject connection

2. `list_projects`

列出你有权访问的所有项目。

参数：

active_only（布尔值，可选）：仅显示活跃项目（默认值：true）

示例：

List all active projects

3. `list_work_packages` ⭐ 增强

列出工作项，并提供高级筛选功能——这是功能最强大的搜索工具。

基本参数：

project_id（整数，可选）：按项目筛选
assignee_id（整数，可选）：按指派人筛选
active_only（布尔值，可选）：仅显示未关闭的任务（默认值：true）
offset（整数，可选）：分页偏移量（默认值：0）
page_size（整数，可选）：每页结果数（默认值：20，最大值：100）

高级筛选器（新增，18 个参数）：

priority_ids（字符串，可选）：逗号分隔的优先级 ID（例如："3,4"）
type_ids（字符串，可选）：逗号分隔的类型 ID（例如："1,2"）
status_ids（字符串，可选）：逗号分隔的状态 ID（优先于 active_only）
version_ids（字符串，可选）：逗号分隔的版本／冲刺 ID
due_before（字符串，可选）：到期日期早于指定日期（YYYY-MM-DD）
due_after（字符串，可选）：到期日期晚于指定日期（YYYY-MM-DD）
created_after（字符串，可选）：创建日期晚于指定日期（YYYY-MM-DD）
updated_after（字符串，可选）：更新日期晚于指定日期（YYYY-MM-DD）
unassigned_only（布尔值，可选）：仅显示未指派的任务
overdue_only（布尔值，可选）：仅显示逾期任务
percentage_done_min（整数，可选）：最低完成百分比（0-100）
percentage_done_max（整数，可选）：最高完成百分比（0-100）
author_id（整数，可选）：按任务创建者筛选
parent_id（整数，可选）：父任务的子任务
no_parent_only（布尔值，可选）：仅显示顶层任务

功能：

总计 23 个参数，灵活性极高
所有筛选条件均采用 AND 逻辑
100% 向后兼容
智能筛选优先级（例如，status_ids > active_only）

示例：

Find high-priority bugs due this week in project 5

Find overdue unassigned tasks

Show tasks 50-80% complete

4. `search_work_packages`

使用服务端筛选功能，按主题或 ID 搜索工作项。

参数：

query（字符串，必填）：用于匹配工作项主题或 ID 的搜索文本
project_id（整数，可选）：将搜索范围限制在特定项目
active_only（布尔值，可选）：仅搜索未关闭的工作项（默认值：true）
offset（整数，可选）：分页起始索引（默认值：0）
page_size（整数，可选）：每页结果数（默认值：20，最大值：100）

示例：

Search for tasks containing "login"

Search for work package by ID: "123"

**注意：**此工具可快速搜索，无需对所有任务进行分页。需要按名称或 ID 查找特定任务时，请使用此工具。

5. `list_types`

列出可用的工作项类型。

参数：

project_id（整数，可选）：按项目筛选类型

示例：

List all work package types

6. `create_work_package`

创建新的工作项。

参数：

project_id（整数，必填）：项目 ID
subject（字符串，必填）：工作项标题
type_id（整数，必填）：类型 ID（例如，1 表示任务）
description（字符串，可选）：Markdown 格式的描述
priority_id（整数，可选）：优先级 ID
assignee_id（整数，可选）：要指派给的用户 ID

示例：

Create a new task in project 5 titled "Update documentation" with type ID 1

7. `list_users`

列出 OpenProject 实例中的所有用户。

参数：

active_only（布尔值，可选）：仅显示活跃用户（默认值：true）

8. `get_user`

获取特定用户的详细信息。

参数：

user_id（整数，必填）：用户 ID

9. `list_memberships`

列出项目成员关系，显示用户及其角色。

参数：

project_id（整数，可选）：按特定项目筛选
user_id（整数，可选）：按特定用户筛选

10. `list_statuses`

列出所有可用的工作项状态。

11. `list_priorities`

列出所有可用的工作项优先级。

12. `get_work_package`

获取特定工作项的详细信息。

参数：

work_package_id（整数，必填）：工作项 ID

13. `update_work_package`

更新现有工作包。

参数：

work_package_id（整数，必填）：工作包 ID
subject（字符串，可选）：工作包标题
description（字符串，可选）：Markdown 格式的描述
type_id（整数，可选）：类型 ID
status_id（整数，可选）：状态 ID
priority_id（整数，可选）：优先级 ID
assignee_id（整数，可选）：要分配给的用户 ID
percentage_done（整数，可选）：完成百分比（0-100）

13. `delete_work_package`

删除工作包。

参数：

work_package_id（整数，必填）：工作包 ID

高级筛选 🔍

以下工具为常见的工作包搜索场景提供专门的筛选功能。所有工具都支持按项目、受指派人、优先级和类型灵活筛选。

14. `list_overdue_work_packages`

列出所有已超过到期日期的工作包。

参数：

project_id（整数，可选）：按项目筛选
assignee_id（整数，可选）：按受指派人筛选
priority_ids（字符串，可选）：以逗号分隔的优先级 ID（例如："3,4"）
type_ids（字符串，可选）：以逗号分隔的类型 ID（例如："1,2"）
page_size（整数，可选）：每页结果数（默认值：50，最大值：100）

功能：

显示每个任务「逾期 X 天」
按逾期时间从长到短排序
仅搜索未关闭的任务

示例：

Find all overdue high-priority tasks in project 5

15. `list_work_packages_due_soon`

列出未来 N 天内到期的工作包。

参数：

days（整数，可选）：向前查看的天数（默认值：7，最大值：365）
project_id（整数，可选）：按项目筛选
assignee_id（整数，可选）：按受指派人筛选
priority_ids（字符串，可选）：以逗号分隔的优先级 ID
page_size（整数，可选）：每页结果数（默认值：50，最大值：100）

功能：

显示「X 天后到期」「明天到期」或「今天到期！」
按到期时间从近到远排序
可配置向前查看的时间范围

示例：

Show me tasks due in the next 3 days

16. `list_unassigned_work_packages`

列出没有受指派人的工作包。

参数：

project_id（整数，可选）：按项目筛选
priority_ids（字符串，可选）：以逗号分隔的优先级 ID
type_ids（字符串，可选）：以逗号分隔的类型 ID
active_only（布尔值，可选）：仅包含未关闭的任务（默认值：true）
page_size（整数，可选）：每页结果数（默认值：50，最大值：100）

功能：

找出需要分配的任务
适用于冲刺规划
支持按优先级和类型筛选

示例：

Find unassigned high-priority bugs in project 5

17. `list_work_packages_created_recently`

列出过去 N 天内创建的工作包。

参数：

days（整数，可选）：向前回溯的天数（默认值：7，最大值：365）
project_id（整数，可选）：按项目筛选
assignee_id（整数，可选）：按受指派人筛选
type_ids（字符串，可选）：以逗号分隔的类型 ID
active_only（布尔值，可选）：仅包含未关闭的任务（默认值：true）
page_size（整数，可选）：每页结果数（默认值：50，最大值：100）

功能：

追踪新建任务的模式
按创建时间从新到旧排序
可配置回溯时间范围

示例：

Show bugs created in the last 3 days

18. `list_high_priority_work_packages`

列出高优先级的工作包。

参数：

project_id（整数，可选）：按项目筛选
assignee_id（整数，可选）：按受派人筛选
type_ids（字符串，可选）：逗号分隔的类型 ID
active_only（布尔值，可选）：仅包含未关闭的任务（默认值：true）
page_size（整数，可选）：每页结果数（默认值：50，最大值：100）

功能：

假定优先级 ID 3 =“高”（典型默认值）
如果需要，会提供使用 list_priorities 的实用提示
快速访问紧急任务

示例：

Show all high-priority tasks in project 5

**注意：**如果你的 OpenProject 实例使用不同的优先级 ID，请使用 list_priorities 查找正确的 ID，然后使用带有特定 priority_ids 参数的增强版 list_work_packages。

19. `list_work_packages_nearly_complete`

列出即将完成的工作包（完成百分比较高）。

参数：

project_id（整数，可选）：按项目筛选
assignee_id（整数，可选）：按受派人筛选
min_percentage（整数，可选）：最低完成百分比（默认值：80，范围：1-99）
active_only（布尔值，可选）：仅包含未关闭的任务（默认值：true）
page_size（整数，可选）：每页结果数（默认值：50，最大值：100）

功能：

找出需要最后冲刺的任务
按完成百分比从高到低排序
包含完成情况摘要部分
适用于冲刺评审

示例：

Show tasks more than 90% complete

20. `list_time_entries`

列出时间条目，可选择筛选条件。

参数：

work_package_id（整数，可选）：按特定工作包筛选
user_id（整数，可选）：按特定用户筛选

15. `create_time_entry`

创建新的时间条目。

参数：

work_package_id（整数，必填）：工作包 ID
hours（数字，必填）：耗时（例如，2.5 小时）
spent_on（字符串，必填）：耗时日期（YYYY-MM-DD 格式）
comment（字符串，可选）：评论／描述
activity_id（整数，可选）：活动 ID

16. `update_time_entry`

更新现有时间条目。

参数：

time_entry_id（整数，必填）：时间条目 ID
hours（数字，可选）：耗时
spent_on（字符串，可选）：耗时日期
comment（字符串，可选）：评论／描述
activity_id（整数，可选）：活动 ID

17. `delete_time_entry`

删除时间条目。

参数：

time_entry_id（整数，必填）：时间条目 ID

18. `list_time_entry_activities`

列出可用的时间条目活动。

19. `list_versions`

列出项目版本／里程碑。

参数：

project_id（整数，可选）：按特定项目筛选

20. `create_version`

创建新的项目版本／里程碑。

参数：

project_id（整数，必填）：项目 ID
name（字符串，必填）：版本名称
description（字符串，可选）：版本描述
start_date（字符串，可选）：开始日期（YYYY-MM-DD 格式）
end_date（字符串，可选）：结束日期（YYYY-MM-DD 格式）
status（字符串，可选）：版本状态（open、locked、closed）

21. `create_project`

创建新项目。

参数：

name（字符串，必填）：项目名称
identifier（字符串，必填）：项目标识符（唯一）
description（字符串，可选）：项目描述
public（布尔值，可选）：项目是否公开
status（字符串，可选）：项目状态
parent_id（整数，可选）：父项目 ID

示例：

Create a new project named "Website Redesign" with identifier "web-redesign"

22. `update_project`

更新现有项目。

参数：

project_id（整数，必填）：项目 ID
name（字符串，可选）：项目名称
identifier（字符串，可选）：项目标识符
description（字符串，可选）：项目描述
public（布尔值，可选）：项目是否公开
status（字符串，可选）：项目状态
parent_id（整数，可选）：父项目 ID

23. `delete_project`

删除项目。

参数：

project_id（整数，必填）：项目 ID

24. `get_project`

获取特定项目的详细信息。

参数：

project_id（整数，必填）：项目 ID

25. `create_membership`

创建新的项目成员关系。

参数：

project_id（整数，必填）：项目 ID
user_id（整数，可选）：用户 ID（如果未提供 group_id，则必填）
group_id（整数，可选）：群组 ID（如果未提供 user_id，则必填）
role_ids（数组，可选）：角色 ID 数组
role_id（整数，可选）：单个角色 ID（作为 role_ids 的替代项）
notification_message（字符串，可选）：可选的通知消息

示例：

Add user 5 to project 2 with role ID 3 (Developer role)

26. `update_membership`

更新现有成员关系。

参数：

membership_id（整数，必填）：成员关系 ID
role_ids（数组，可选）：角色 ID 数组
role_id（整数，可选）：单个角色 ID
notification_message（字符串，可选）：可选的通知消息

27. `delete_membership`

删除成员关系。

参数：

membership_id（整数，必填）：成员关系 ID

28. `get_membership`

获取特定成员关系的详细信息。

参数：

membership_id（整数，必填）：成员关系 ID

29. `list_project_members`

列出特定项目的所有成员。

参数：

project_id（整数，必填）：项目 ID

示例：

List all members of project 5

30. `list_user_projects`

列出分配给特定用户的所有项目。

参数：

user_id（整数，必填）：用户 ID

31. `list_roles`

列出所有可用角色。

示例：

List all available roles in the OpenProject instance

32. `get_role`

获取特定角色的详细信息。

参数：

role_id（整数，必填）：角色 ID

33. `set_work_package_parent`

为工作包设置父级（创建父子关系）。

参数：

work_package_id（整数，必填）：要设为子级的工作包 ID
parent_id（整数，必填）：要设为父级的工作包 ID

示例：

Set work package 15 as a child of work package 10

34. `remove_work_package_parent`

移除工作包的父级关系（使其成为顶级工作包）。

参数：

work_package_id（整数，必填）：要移除父级关系的工作包 ID

35. `list_work_package_children`

列出父级工作包的所有子工作包。

参数：

parent_id（整数，必填）：父工作包 ID
include_descendants（布尔值，可选）：包含孙级及所有后代（默认值：false）

示例：

List all children of work package 10 including descendants

36. `create_work_package_relation`

创建工作包之间的关系。

参数：

from_id（整数，必填）：源工作包 ID
to_id（整数，必填）：目标工作包 ID
relation_type（字符串，必填）：关系类型（blocks、follows、precedes、relates、duplicates、includes、requires、partof）
lag（整数，可选）：滞后工作日数（用于 follows/precedes）
description（字符串，可选）：关系的可选描述

示例：

Create a "blocks" relation where work package 5 blocks work package 8

37. `list_work_package_relations`

列出工作包关系，可选择筛选条件。

参数：

work_package_id（整数，可选）：筛选涉及此工作包 ID 的关系
relation_type（字符串，可选）：按关系类型筛选

38. `update_work_package_relation`

更新现有工作包关系。

参数：

relation_id（整数，必填）：关系 ID
relation_type（字符串，可选）：新的关系类型
lag（整数，可选）：滞后工作日数
description（字符串，可选）：可选描述

39. `delete_work_package_relation`

删除工作包关系。

参数：

relation_id（整数，必填）：关系 ID

40. `get_work_package_relation`

获取特定工作包关系的详细信息。

参数：

relation_id（整数，必填）：关系 ID

开发

设置开发环境

# Install development dependencies
uv sync --extra dev

# Or install manually
uv pip install -e ".[dev]"

运行测试

uv run pytest tests/

代码格式化

# Format code
uv run black openproject-mcp.py

# Lint code
uv run flake8 openproject-mcp.py

添加依赖项

# Add a new dependency
uv add package-name

# Add a development dependency
uv add --dev package-name

# Update dependencies
uv sync

工具兼容性与测试结果

✅ 完全正常工作的工具（40/42）

所有这些工具均已使用管理员权限进行测试，并且工作正常：

核心项目管理：

test_connection、check_permissions、list_projects、create_project、update_project
delete_project、get_project

工作包管理：

list_work_packages、search_work_packages、list_types、create_work_package、update_work_package
delete_work_package、get_work_package、list_statuses、list_priorities

工作包层级与关联：

set_work_package_parent、remove_work_package_parent、list_work_package_children
create_work_package_relation、list_work_package_relations、update_work_package_relation
delete_work_package_relation、get_work_package_relation

用户与成员管理：

list_users、get_user、create_membership、update_membership、delete_membership
get_membership、list_project_members、list_user_projects、list_roles、get_role

时间跟踪：

list_time_entries、create_time_entry、update_time_entry、delete_time_entry

项目版本：

list_versions、create_version

⚠️ 部分正常工作的工具

list_memberships：可在全局范围内使用，也支持通过 project_id 筛选。并非所有 OpenProject 实例都支持按用户 ID（user_id）筛选。

❌ 端点限制及解决方法

list_time_entry_activities：会返回 404，但时间条目活动实际可用！请使用以下预定义的活动 ID：
- 管理（ID：1）：行政与规划任务
- 规格说明（ID：2）：需求与文档编写
- 开发（ID：3）：编码与实现
- 测试（ID：4）：质量保证与测试

示例：开发工作可通过 activity_id: 3 调用 create_time_entry

权限要求

大多数创建、更新和删除操作都需要相应权限：

项目操作：需要全局“创建项目”和“编辑项目”权限。删除通常需要管理员权限
工作包操作：需要在目标项目中拥有“创建／编辑工作包”权限
工作包关联与层级：创建或修改父子关系和依赖关系需要“编辑工作包”权限
成员管理：需要拥有目标项目的“管理成员”权限
时间条目操作：需要时间跟踪权限
版本管理：需要项目管理员权限或版本管理权限
用户操作：全面管理用户可能需要管理员权限
角色管理：通常可执行只读操作；查看详细角色信息可能需要管理员权限

使用 check_permissions 工具诊断权限相关问题。

故障排除

连接问题

401 未授权：检查 API 密钥是否正确且处于启用状态
403 禁止访问：确保你的用户拥有所需权限
404 未找到：确认 OpenProject URL 正确且资源存在
代理错误：检查代理设置和身份验证

调试模式

通过设置以下内容启用调试日志：

LOG_LEVEL=DEBUG

常见问题

未找到项目：确保你的 API 用户拥有查看项目的权限
SSL 错误：使用自签名证书或代理 SSL 拦截时可能会发生
超时错误：增加超时时间或检查网络连接

安全注意事项

切勿将 .env 文件提交到版本控制系统
使用环境变量存储敏感数据
定期轮换 API 密钥
所有 OpenProject 连接均使用 HTTPS
如需配置代理身份验证，请确保配置安全

贡献

Fork 此仓库
创建功能分支（git checkout -b feature/amazing-feature）
提交更改（git commit -m 'Add amazing feature'）
将分支推送到远程仓库（git push origin feature/amazing-feature）
发起 Pull Request

许可证

本项目采用 MIT License 许可，详情请参阅 LICENSE 文件。

致谢

为 Model Context Protocol 构建
与 OpenProject 集成
灵感来自 MCP 社区

支持

🐛 问题：GitHub Issues
💬 讨论：GitHub Discussions

支持 Markdown

登录后评论

第一次接触 MCP？

从协议是什么，到在客户端里装上第一个服务，这几条回答覆盖了大多数入门问题。

阅读入门指南

一个开放协议，规定了 AI 应用如何以统一方式连接外部工具与数据源。客户端负责与模型对话，MCP 服务负责提供工具、资源和提示模板，两者通过标准消息通信，同一个服务可以被不同客户端复用。

OpenProject MCP

关于 OpenProject MCP

主要功能

适用场景

MCP 相关

配置

工具

详细介绍

OpenProject MCP 服务

功能

前提条件

安装

1. 安装 uv（如果尚未安装）

2. 克隆并设置项目

3. 创建虚拟环境并安装依赖项

4. 配置环境

配置

环境变量

获取 API 密钥

使用方法

部署选项

选项 1：本地部署（stdio）

运行服务

与 Claude Desktop 集成

选项 2：云端部署（FastMCP Cloud）☁️

可用工具

1. test_connection

2. list_projects

3. list_work_packages ⭐ 增强

4. search_work_packages

5. list_types

6. create_work_package

7. list_users

8. get_user

9. list_memberships

10. list_statuses

11. list_priorities

12. get_work_package

13. update_work_package

13. delete_work_package

高级筛选 🔍

14. list_overdue_work_packages

15. list_work_packages_due_soon

16. list_unassigned_work_packages

17. list_work_packages_created_recently

18. list_high_priority_work_packages

19. list_work_packages_nearly_complete

20. list_time_entries

15. create_time_entry

16. update_time_entry

17. delete_time_entry

18. list_time_entry_activities

19. list_versions

20. create_version

21. create_project

22. update_project

23. delete_project

24. get_project

25. create_membership

26. update_membership

27. delete_membership

28. get_membership

29. list_project_members

30. list_user_projects

31. list_roles

32. get_role

33. set_work_package_parent

34. remove_work_package_parent

35. list_work_package_children

36. create_work_package_relation

37. list_work_package_relations

38. update_work_package_relation

39. delete_work_package_relation

40. get_work_package_relation

开发

设置开发环境

运行测试

代码格式化

添加依赖项

工具兼容性与测试结果

1. `test_connection`

2. `list_projects`

3. `list_work_packages` ⭐ 增强

4. `search_work_packages`

5. `list_types`

6. `create_work_package`

7. `list_users`

8. `get_user`

9. `list_memberships`

10. `list_statuses`

11. `list_priorities`

12. `get_work_package`

13. `update_work_package`

13. `delete_work_package`

14. `list_overdue_work_packages`

15. `list_work_packages_due_soon`

16. `list_unassigned_work_packages`

17. `list_work_packages_created_recently`

18. `list_high_priority_work_packages`

19. `list_work_packages_nearly_complete`

20. `list_time_entries`

15. `create_time_entry`

16. `update_time_entry`

17. `delete_time_entry`

18. `list_time_entry_activities`

19. `list_versions`

20. `create_version`

21. `create_project`

22. `update_project`

23. `delete_project`

24. `get_project`

25. `create_membership`

26. `update_membership`

27. `delete_membership`

28. `get_membership`

29. `list_project_members`

30. `list_user_projects`

31. `list_roles`

32. `get_role`

33. `set_work_package_parent`

34. `remove_work_package_parent`

35. `list_work_package_children`

36. `create_work_package_relation`

37. `list_work_package_relations`

38. `update_work_package_relation`

39. `delete_work_package_relation`

40. `get_work_package_relation`