AI导哈

OpenProject MCP服务

一个使AI助手能够与OpenProject安装交互的模型上下文协议服务器，支持通过自然语言命令创建项目、管理工作包、分配团队成员和生成甘特图。

  • by Tangaratta-Engineering
  • Python
  • 本地部署
  • 15 星标
  • 更新于
在 GitHub 查看 firsthalfhero/openproject-mcp-server

使用说明

OpenProject MCP服务器

一种模型上下文协议（MCP）服务器，使AI助手能够与OpenProject安装进行交互。通过自然语言命令创建项目、管理工作包、分配团队成员和生成甘特图。

特性

  • 项目管理：创建和管理OpenProject项目
  • 工作包操作：创建、更新和分配带有日期的工作包
  • 依赖管理：为甘特图创建工作包之间的关系
  • 用户管理：通过电子邮件地址查找和分配用户
  • 团队协作：管理项目成员及其角色
  • 动态配置：自动加载工作包类型、状态和优先级
  • 全面报道：项目状态报告和团队工作量分析

安装

先决条件

  • OpenProject实例（本地或云）
  • OpenProject配置文件中的API密钥
  • Python 3.8+或Docker

方法一：Docker（推荐）

  1. 克隆仓库:

    git clone <repository-url>
cd openproject-mcp-server

  2. 配置环境:

    cp env.example .env
# Edit .env with your OpenProject details

  3. 使用Docker进行部署:

    ./scripts/deploy.sh deploy 39127

方法2：Python

  1. 克隆和设置:

    git clone <repository-url>
cd openproject-mcp-server
python3 -m venv venv
source venv/bin/activate  # On Windows: venv\Scripts\activate
pip install -r requirements.txt

  2. 配置环境:

    cp env.example .env
# Edit .env with your OpenProject details

  3. 测试配置:

    python3 scripts/test_mvp.py

配置

创建 .env 包含您的OpenProject详细信息的文件：

# OpenProject Instance URL (include protocol)
OPENPROJECT_URL=http://localhost:8080

# OpenProject API Key (from your user profile)
OPENPROJECT_API_KEY=your_40_character_api_key_here

# MCP Server Configuration (optional)
MCP_HOST=localhost
MCP_PORT=39127
MCP_LOG_LEVEL=INFO

获取OpenProject API密钥

  1. 登录到您的OpenProject实例
  2. 首选 我的账户 → 访问令牌
  3. 点击 +新代币
  4. 输入名称（例如“MCP服务器”）
  5. 复制生成的40个字符的令牌

用法

启动服务器

Docker：

./scripts/deploy.sh deploy 39127

python

python3 scripts/run_server.py

MCP客户端配置

克劳德桌面版

添加到您的 claude_desktop_config.json:

对于Docker部署：

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

对于本地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"
      }
    }
  }
}

其他MCP客户端

使用SSE传输URL： http://localhost:39127/sse

可用工具

项目管理

  • create_project -创建新项目
  • get_projects -列出所有项目
  • get_project_summary -获取详细的项目概述
  • get_project_members -列出项目成员和角色

工作包管理

  • create_work_package -创建包含日期和任务的工作包
  • get_work_packages -列出项目的工作包
  • update_work_package -更新现有工作包
  • assign_work_package_by_email -使用电子邮件地址分配工作包

依赖管理

  • create_work_package_dependency -为甘特图创建关系
  • get_work_package_relations -列出工作包的依赖关系
  • delete_work_package_relation -删除关系

用户管理

  • get_users -列出具有可选电子邮件过滤功能的用户

配置

  • get_work_package_types -列出可用的工作包类型
  • get_work_package_statuses -列出可用状态
  • get_priorities -列出可用优先级

示例命令

一旦与AI助手集成，您就可以使用自然语言：

与团队一起创建项目：

Create a project called "Website Redesign" and add john@example.com and sarah@example.com to the team.

创建具有依赖关系的工作包：

In project ID 5, create:
1. "Requirements Analysis" from 2024-01-15 to 2024-01-20, assign to john@example.com
2. "UI Design" from 2024-01-21 to 2024-02-05, assign to sarah@example.com
3. "Development" from 2024-02-06 to 2024-02-28

Make UI Design depend on Requirements Analysis, and Development depend on UI Design.

获取项目状态：

Show me a summary of project ID 5 including all work packages and team assignments.

资源

服务器为浏览OpenProject数据提供只读资源：

  • openproject://projects -列出所有项目
  • openproject://project/{project_id} -获取具体项目详细信息
  • openproject://work-packages/{project_id} -获取项目的工作包
  • openproject://work-package/{work_package_id} -获取具体的工作包详细信息

Docker管理

部署命令

# Deploy on port 39127 (recommended)
./scripts/deploy.sh deploy 39127

# View logs
./scripts/deploy.sh logs

# Check status
./scripts/deploy.sh status

# Stop server
./scripts/deploy.sh stop

# Restart server
./scripts/deploy.sh restart

# Clean up (remove container and image)
./scripts/deploy.sh clean

手动Docker命令

# Build image
docker build -t openproject-mcp-server .

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

故障排除

连接问题

  • 验证OpenProject URL是否可访问
  • 检查API密钥是否正确（40个字符）
  • 确保已启用OpenProject API

权限问题

  • 验证您的用户是否具有项目创建权限
  • 检查目标项目中的工作包创建权限

日期格式问题

  • 所有日期均使用YYYY-MM-DD格式
  • 确保due_date在start_date之后

Docker问题

# Check container status
docker ps

# View container logs
docker logs openproject-mcp-server

# Test API endpoint
curl http://localhost:39127/sse

测试

# Test basic connection
python3 scripts/test_mvp.py

# Run comprehensive tests
python3 tests/run_tests.py

# Run with pytest
pip install -r requirements-test.txt
python3 -m pytest tests/ -v

发展

项目结构

openproject-mcp-server/
├── src/                    # Source code
├── scripts/               # Deployment and test scripts
├── tests/                 # Test suite
├── docker-compose.yml     # Docker configuration
├── Dockerfile            # Container build instructions
└── requirements.txt      # Python dependencies

运行测试

# Install test dependencies
pip install -r requirements-test.txt

# Run all tests
python3 -m pytest tests/ -v

# Run with coverage
python3 -m pytest --cov=src --cov-report=html tests/

贡献

  1. 分叉存储库
  2. 创建要素分支
  3. 进行更改
  4. 添加新功能的测试
  5. 确保所有测试通过
  6. 提交拉取请求

许可证

[许可证信息]

支持

对于问题和疑问：

  1. 检查上面的故障排除部分
  2. 查看容器日志： docker logs openproject-mcp-server
  3. 测试您的OpenProject API连接
  4. 在中验证您的配置 .env 文件

相关 MCP