本项目实现了 MCP (Model Context Protocol) 协议与 OpenProject 的集成，为团队领导者提供项目管理工具。通过标准化的 MCP 接口，可以集成到各种 AI 助手和自动化工具中。
3 stars
Python
Updated Oct 24, 2025
mcp
open-project
Documentation
OpenProject MCP 服务器
🎯 为团队领导者提供智能化的项目报告生成工具
✨ 核心功能
- 📊 智能报告生成 - 自动生成周报、月报、进度报告
- 🎯 风险评估 - 实时项目风险识别和评估
- 👥 工作负载分析 - 团队成员工作量分析和优化建议
- 🎨 模板系统 - 支持自定义报告模板，包含专业的日本式商务报告
- 🔌 MCP 协议 - 标准协议，易于集成到 Claude Desktop、Cursor 等 AI 工具
🚀 快速开始
📋 解决方案选择指南
| 解决方案 | 稳定性 | 推荐场景 | 端口 |
|---|---|---|---|
| HTTP 方案 | ✅ 生产稳定 | 生产环境部署 | 8010 |
| FastAPI 方案 | ✅ 功能完整 | 开发测试使用 | 8020 |
| FastMCP 方案 | ⚠️ 实验性 | 技术评估测试 | 8010 |
生产环境推荐使用 HTTP 解决方案
1. 启动 OpenProject (可选)
bash
# 使用 Docker 启动 OpenProject (如果还没有 OpenProject 实例)
docker-compose up -d
# 访问 OpenProject: http://localhost:8090
# 默认账号: admin / admin2. 选择并启动解决方案
🎯 方案一：HTTP 解决方案 (推荐生产使用)
bash
cd solution-http
python3 -m venv venv
source venv/bin/activate # Windows: venv\Scripts\activate
pip install -r requirements.txt
pip install -e ../mcp-core
# 配置环境变量
cp .env.example .env
# 编辑 .env 文件，设置 OpenProject URL 和 API Key
# 启动服务
python3 -m src.main🚀 方案二：FastAPI 解决方案 (推荐开发使用)
bash
cd solution-fastapi
python3 -m venv venv
source venv/bin/activate # Windows: venv\Scripts\activate
pip install -r requirements.txt
pip install -e ../mcp-core
# 配置环境变量
cp .env.example .env
# 编辑 .env 文件，设置 OpenProject URL 和 API Key
# 启动服务
python app/main.py💡 详细启动说明: 查看 服务启动操作手册
3. 访问服务
HTTP 解决方案 (端口 8010)
- 🌐 Web 界面: http://localhost:8010/web/template_editor.html
- 🔌 MCP 端点: http://localhost:8010/mcp
- ❤️ 健康检查: http://localhost:8010/health
- 📋 服务信息: http://localhost:8010/
FastAPI 解决方案 (端口 8020)
- 🌐 Web 界面: http://localhost:8020/web/template_editor.html
- 🔌 MCP 端点: http://localhost:8020/mcp
- 📖 API 文档: http://localhost:8020/docs
- ❤️ 健康检查: http://localhost:8020/health
- 📋 服务信息: http://localhost:8020/
🎨 模板系统
支持多种专业报告模板：
- 日本式週報 - 符合日本商务文化的详细周报
- 日本式月報 - 综合的月度总结报告
- 日本式進捗報告 - 专业的进度状况报告
- 自定义模板 - 通过 Web 界面创建和编辑
🔧 集成到 AI 工具
Claude Desktop
json
{
"mcpServers": {
"openproject": {
"command": "curl",
"args": ["-X", "POST", "http://localhost:8020/mcp"]
}
}
}Cursor
在 Cursor 中添加 MCP 服务器配置，指向 http://localhost:8020/mcp
📚 使用示例
生成周报 (使用 HTTP 解决方案)
bash
curl -X POST http://localhost:8010/mcp \
-H "Content-Type: application/json" \
-d '{
"jsonrpc": "2.0",
"id": 1,
"method": "tools/call",
"params": {
"name": "generate_report_from_template",
"arguments": {
"template_id": "japanese_weekly_report",
"project_id": "1"
}
}
}'评估项目风险
bash
curl -X POST http://localhost:8010/mcp \
-H "Content-Type: application/json" \
-d '{
"jsonrpc": "2.0",
"id": 2,
"method": "tools/call",
"params": {
"name": "assess_project_risks",
"arguments": {
"project_id": "1"
}
}
}'📖 更多使用示例: 查看 服务启动操作手册
🔧 配置
环境变量
bash
# OpenProject 配置（必需）
OPENPROJECT_URL=https://your-openproject.com
OPENPROJECT_API_KEY=your-api-key-here
# 服务器配置 (HTTP 解决方案)
HOST=0.0.0.0
PORT=8010
LOG_LEVEL=INFO
# 服务器配置 (FastAPI 解决方案)
PORT=8020 # 注意端口不同🔧 详细配置说明: 查看 服务启动操作手册
获取 API Key
1. 登录 OpenProject
2. 进入 "我的账户" → "访问令牌"
3. 创建新的 API 密钥
4. 复制密钥到 .env 文件
🆘 故障排除
常见问题
Q: 服务启动失败，提示端口被占用
bash
# 查找占用端口的进程并终止
lsof -ti:8010 | xargs kill -9 # HTTP 解决方案端口
lsof -ti:8020 | xargs kill -9 # FastAPI 解决方案端口
# 或者修改配置使用其他端口
# 在 .env 文件中修改 PORT 设置Q: 无法连接到 OpenProject
- 检查 OpenProject 是否正在运行
- 验证 API Key 是否正确
- 确认网络连接正常
- 查看服务器日志获取详细错误信息
Q: 模板预览生成失败
- 检查项目 ID 是否存在
- 确认有访问该项目的权限
- 查看服务器日志获取详细错误信息
🔧 更多故障排除: 查看 服务启动操作手册
📄 许可证
MIT License - 详见 LICENSE 文件
🤝 贡献
欢迎提交 Issue 和 Pull Request！
---
📖 扩展文档
查看 docs/ 目录获取详细文档：
- 🚀 服务启动操作手册 - 详细的安装、配置和使用指南
- 🏗️ 架构优化计划 - 项目架构优化和实施路线图
- 📚 文档索引 - 所有文档的分类和导航指南
- 🔌 FastAPI 集成示例 - 如何集成到其他应用
服务链接:
- HTTP 解决方案: http://localhost:8010
- FastAPI 解决方案: http://localhost:8020/docs
- Web 模板编辑器: http://localhost:8010/web/template_editor.html
Similar MCP
Based on tags & features
Trending MCP
Most active this week