开源项目-MCP服务器

Name: 开源项目-MCP服务器
Author: firsthalfhero

作者：firsthalfhero2 星标更新：2025-08-15

安装使用来源：spider==github.com

项目介绍

OpenProject MCP Server

一个全面的FastMCP驱动服务器，使像Claude这样的AI助手能够与OpenProject安装进行交互。此实现提供了完整的项目管理功能，包括用户管理、动态配置以及高级甘特图创建。

🎯 核心功能

MVP 功能

✅ 通过AI助手在OpenProject中创建项目
✅ 创建带有开始/截止日期的工作包以生成甘特图
✅ 在工作包之间创建依赖关系
✅ 在OpenProject中生成正确的甘特图
✅ 从AI命令到可视化时间线的端到端工作流

第一阶段增强功能

✅ 用户管理 - 通过电子邮件地址查找并分配用户
✅ 动态配置 - 自动加载类型、状态和优先级
✅ 基于电子邮件的分配 - 不需要知道用户ID即可分配工作包
✅ 项目成员管理 - 查看项目成员及其角色
✅ 增强错误处理 - 详细的验证和错误消息
✅ 性能优化 - 智能缓存和分页

🚀 快速入门

先决条件

OpenProject 实例：您需要一个正在运行的OpenProject安装（本地或云端）
API 密钥：从您的OpenProject个人资料生成API密钥
Python 3.8+：运行MCP服务器所需

安装

克隆或下载项目：
```
cd openproject-mcp-server
```

创建并激活虚拟环境：

python3 -m venv venv
source venv/bin/activate  # 在Windows上：venv\Scripts\activate

安装依赖项：
```
pip install -r requirements.txt
```

配置环境：

cp env.example .env
# 使用您的OpenProject详细信息编辑.env文件

配置

使用您的OpenProject详细信息编辑.env文件：

# OpenProject 实例URL（包含协议）
OPENPROJECT_URL=http://localhost:3000

# OpenProject API密钥（来自您的用户个人资料）
OPENPROJECT_API_KEY=your_40_character_api_key_here

# MCP服务器配置（可选）
MCP_HOST=localhost
MCP_PORT=8080
MCP_LOG_LEVEL=INFO

获取您的OpenProject API密钥：

登录到您的OpenProject实例
转到我的账户 → 访问令牌
点击**+ 新建令牌**
输入名称（例如，“MCP服务器”）
复制生成的40个字符的令牌

测试

在使用AI助手之前测试您的配置：

python3 scripts/test_mvp.py

这将：

✅ 测试OpenProject API连接
✅ 创建测试项目
✅ 创建带有日期的工作包
✅ 创建依赖关系
✅ 验证甘特图准备情况

运行服务器

启动MCP服务器：

python3 scripts/run_server.py

服务器将启动并准备好接受AI助手连接。

🐳 Docker部署

Docker部署是推荐的生产方法。

Docker先决条件

已安装Docker（版本20.10+）
Docker Compose（用于更简单的管理）
配置.env文件，包含您的OpenProject详细信息

使用Docker快速入门

选项1：自动化部署（推荐）

# 首先配置您的环境
cp env.example .env
# 使用您的OpenProject URL和API密钥编辑.env文件

# 在特定端口上部署（重要：必须匹配Claude Desktop配置）
./scripts/deploy.sh deploy 39127

# 可选：在默认端口8080上部署
./scripts/deploy.sh deploy

# 开发时使用不同端口
./scripts/deploy.sh deploy 9876

🔑 重要：端口必须与您的Claude Desktop MCP配置中的~/.cursor/mcp.json或claude_desktop_config.json一致！

选项2：Docker Compose（替代方案）

# 构建并启动容器
docker-compose up -d

# 查看日志
docker-compose logs -f

# 停止容器
docker-compose down

🔧 端口配置及冲突：

步骤1：选择您的端口（必须一致）

# 检查当前的MCP配置
cat ~/.cursor/mcp.json | grep openproject -A 5

# 或检查Claude Desktop配置
cat ~/Library/Application\ Support/Claude/claude_desktop_config.json

步骤2：在MCP配置相同的端口上部署

# 在MCP配置指定的端口上部署
./scripts/deploy.sh deploy 39127

步骤3：如果发生端口冲突：

停止占用该端口的服务：docker stop container_using_port
或更新MCP配置和部署端口以保持一致
检查什么服务占用了该端口：docker ps | grep 39127

手动Docker命令

对于希望完全控制的高级用户：

构建镜像：

docker build -t openproject-mcp-server .

运行容器：

docker run -d \
  --name openproject-mcp-server \
  --env-file .env \
  -p 39127:8080 \
  -v ./logs:/app/logs \
  -v ./data:/app/data \
  --restart unless-stopped \
  openproject-mcp-server

健康检查：

# 检查容器是否健康
docker ps

# 查看容器日志
docker logs openproject-mcp-server

# 测试API端点（注意：MCP服务器没有健康端点）
curl http://localhost:39127/sse

部署脚本命令

scripts/deploy.sh脚本提供全面的部署管理：

# 在标准MCP端口上部署（推荐）
./scripts/deploy.sh deploy 39127

# 在默认端口8080上部署（可能与OpenProject冲突）
./scripts/deploy.sh deploy

# 如果需要在其他端口上部署
./scripts/deploy.sh deploy 9876

# 查看容器日志
./scripts/deploy.sh logs

# 检查状态和端口信息
./scripts/deploy.sh status

# 停止服务器
./scripts/deploy.sh stop

# 重启服务器（保持同一端口）
./scripts/deploy.sh restart

# 清理（停止并删除容器/镜像）
./scripts/deploy.sh clean

💡 端口选择提示：

端口39127：推荐的MCP标准端口，匹配默认配置
端口8080：默认HTTP端口，但经常与OpenProject冲突
端口9876：好的替代端口，很少冲突
端口8090：常见的开发端口

Docker部署环境变量

使用Docker时，在您的.env文件中配置这些环境变量：

# OpenProject 实例URL（您的OpenProject运行的地方，通常端口8080）
OPENPROJECT_URL=http://localhost:8080

# OpenProject API密钥（来自您的用户个人资料）
OPENPROJECT_API_KEY=your_40_character_api_key_here

# MCP服务器配置（内部容器端口，映射到39127）
MCP_HOST=0.0.0.0
MCP_PORT=8080
MCP_LOG_LEVEL=INFO

# 可选：性能调整（第一阶段功能）
OPENPROJECT_CACHE_TIMEOUT_MINUTES=5
OPENPROJECT_PAGINATION_SIZE=100
OPENPROJECT_MAX_RETRIES=3

Docker部署最佳实践

始终使用.env文件 - 不要在命令中硬编码凭据
卷映射 - 映射日志和数据目录以持久化
健康检查 - 容器内置健康监控
自动重启 - 生产中使用--restart unless-stopped
资源限制 - 考虑添加内存/CPU限制以优化生产

🤖 AI助手集成

Claude Desktop集成

在您的claude_desktop_config.json中添加：

选项1：本地Python执行

{
  "mcpServers": {
    "openproject": {
      "command": "python3",
      "args": ["/full/path/to/openproject-mcp-server/scripts/run_server.py"],
      "env": {
        "OPENPROJECT_URL": "http://localhost:8080",
        "OPENPROJECT_API_KEY": "your_api_key_here"
      }
    }
  }
}

选项2：Docker部署（推荐）

{
  "mcpServers": {
    "openproject": {
      "transport": "sse",
      "url": "http://localhost:39127/sse"
    }
  }
}

环境设置：在Docker部署的.env文件中配置OpenProject凭据，而不是MCP配置。

重要说明：

对于选项1，请使用run_server.py脚本的完整绝对路径
在使用选项2之前确保Docker容器正在运行
OPENPROJECT_URL应指向您的OpenProject实例（通常是端口8080）
MCP服务器URL（端口39127）应在传输URL中单独配置

使用示例

一旦与Claude集成，您可以询问：

创建带有团队成员的项目

创建一个新的名为“网站重新设计”的项目，描述为“公司网站的全面重新设计”。然后显示可用用户，并将john@example.com和sarah@example.com添加到项目中。

基于电子邮件分配的工作包

在项目ID 5中，创建以下工作包：
1. “需求分析”从2024年1月15日至2024年1月20日，分配给john@example.com
2. “UI设计”从2024年1月21日至2024年2月5日，分配给sarah@example.com
3. “开发”从2024年2月6日至2024年2月28日，分配给mike@example.com
4. “测试与发布”从2024年3月1日至2024年3月10日，分配给alice@example.com

创建甘特图的依赖关系

创建依赖关系，使得：
- UI设计跟随需求分析
- 开发跟随UI设计
- 测试跟随开发

用户管理示例

显示系统中的所有用户
查找电子邮件为“john@example.com”的用户
显示项目ID 5的所有成员及其角色

动态配置示例

在此OpenProject实例中有哪些可用的工作包类型？
显示所有可能的工作包状态
我可以使用哪些优先级级别来设置工作包？

AI将使用增强的MCP工具创建一切，并在OpenProject中获得带有正确用户分配的甘特图！

🛠️ 可用工具

OpenProject MCP服务器为AI助手提供了全面的工具：

核心工具（MVP）

`create_project`

目的：在OpenProject中创建新项目
参数：
- name（必需）：项目名称
- description（可选）：项目描述
返回值：带有ID和URL的项目详情

`create_work_package`

目的：创建带有日期的工作包以生成甘特图
参数：
- project_id（必需）：目标项目ID
- subject（必需）：工作包标题
- description（可选）：详细描述
- start_date（可选）：开始日期，YYYY-MM-DD格式
- due_date（可选）：截止日期，YYYY-MM-DD格式
- parent_id（可选）：父工作包ID
- assignee_id（可选）：要分配的用户ID
- estimated_hours（可选）：预计完成时间

`create_work_package_dependency`

目的：在工作包之间创建依赖关系以生成甘特图
参数：
- from_work_package_id（必需）：源工作包ID
- to_work_package_id（必需）：目标工作包ID
- relation_type（可选）：关系类型（follows, precedes, blocks, blocked, relates, duplicates, duplicated）
- description（可选）：关系描述
lag（可选）：前驱任务结束与后继任务开始之间的工日数

`get_work_package_relations`

目的：获取特定工作包的所有关系
参数：
- work_package_id（必需）：要获取关系的工作包ID
返回值：带有详细信息的关系列表

`delete_work_package_relation`

目的：删除工作包关系
参数：
- relation_id（必需）：要删除的关系ID
返回值：删除确认

第一阶段增强工具（用户管理和动态配置）

`get_users`

目的：获取用户列表，可选电子邮件过滤
参数：
- email_filter（可选）：搜索特定用户的电子邮件地址
返回值：带有完整详细信息的用户列表（姓名、电子邮件、角色等）

`assign_work_package_by_email`

目的：通过电子邮件地址分配工作包
参数：
- work_package_id（必需）：要分配的工作包ID
- assignee_email（必需）：要分配的用户的电子邮件地址
返回值：带有用户和工作包详细信息的分配确认

`get_project_members`

目的：获取项目成员及其角色的列表
参数：
- project_id（必需）：要获取成员的项目ID
返回值：带有角色和权限的项目成员列表

`get_work_package_types`

目的：从OpenProject实例获取可用的工作包类型
参数：无
返回值：带有配置的工作包类型列表（任务、错误、功能等）

`get_work_package_statuses`

目的：从OpenProject实例获取可用的工作包状态
参数：无
返回值：带有配置的状态列表（新建、进行中、关闭等）

`get_priorities`

目的：从OpenProject实例获取可用的工作包优先级
参数：无
返回值：带有配置的优先级列表（低、正常、高）

额外增强工具

`get_projects`

目的：列出OpenProject中的所有项目
参数：无
返回值：带有详细信息的所有项目的列表

`get_work_packages`

目的：获取特定项目的工作包
参数：
- project_id（必需）：要获取工作包的项目ID
返回值：带有详细信息的工作包列表

`update_work_package`

目的：更新现有工作包
参数：
- work_package_id（必需）：要更新的工作包ID
- subject（可选）：新的标题
- description（可选）：新的描述
- start_date（可选）：新的开始日期
- due_date （可选）：新的截止日期
- assignee_id（可选）：新的分配人
- estimated_hours（可选）：新的时间估计

`get_project_summary`

目的：获取综合项目概述
参数：
- project_id（必需）：要总结的项目ID
返回值：带有指标的详细项目分析

📊 可用资源

资源提供对OpenProject数据的只读访问：

openproject://projects - 列出所有项目
openproject://project/{project_id} - 获取特定项目的详细信息
openproject://work-packages/{project_id} - 获取项目的工件
openproject://work-package/{work_package_id} - 获取特定工件的详细信息
openproject://work-package-relations/{work_package_id} - 获取工件的关系

🎯 可用提示

提示提供AI辅助的项目管理：

`project_status_report`

目的：生成综合项目状态分析
参数：project_id（必需）
返回值：结构化的项目健康分析提示

`work_package_summary`

目的：汇总工件，带过滤
参数：
- project_id（必需）
- status_filter（可选）：按状态过滤
返回值：组织良好的工件摘要

`project_planning_assistant`

目的：帮助规划新项目结构
参数：
- project_name（必需）：要规划的项目名称
- work_package_count（可选）：建议的工作包数量
返回值：项目规划指导

`team_workload_analysis`

目的：分析团队在项目中的工作量
参数：project_ids（可选）：要分析的项目列表
返回值：团队工作量和容量分析

📊 甘特图工作流程

MVP特别设计用于创建正确的甘特图：

创建项目 → 获取项目ID