Openproject MCP Oauth

具有OAuth身份验证的OpenProject MCP服务器

用于OpenProject的生产就绪模型上下文协议（MCP）服务器，具有OAuth 2.0身份验证，专为与Claude AI和其他MCP客户端一起使用而设计。

特性

• 🔐 OAuth 2.0身份验证 -MCP服务器的安全访问控制
• 🚀 基于FastAPI -高性能异步API包装器
• 🐳 Docker就绪 -完成容器化设置
• 🔌 穿山甲兼容 -与穿山甲隧道配合使用，确保安全通行
• 📊 完全开放项目API -创建项目、工作包、管理依赖关系
• 🎯 Claude AI集成 -专为Claude定制连接器而设计

建筑

Claude Custom Connector
    ↓ OAuth 2.0
Your Public Domain
    ↓ Pangolin/Reverse Proxy
OAuth Wrapper Container
    ↓ Internal Network
MCP Server Container
    ↓ API Token
Your OpenProject Instance

快速开始

先决条件

• Docker和Docker Compose
• 具有API访问权限的OpenProject实例
• （可选）穿山甲或反向代理供公众访问
• Python 3.11+（用于生成机密）

1.克隆/下载文件

将这些文件下载到您的服务器：

• docker-compose.yml
• Dockerfile.oauth
• oauth_mcp_wrapper.py
• .env.example

2.配置环境

# Copy the example environment file
cp .env.example .env

# Edit .env and fill in all required values
nano .env

所需设置：

• OPENPROJECT_URL -您的OpenProject实例URL
• OPENPROJECT_API_KEY -来自OpenProject的API令牌
• OAUTH_SECRET_KEY -使用以下命令生成
• OAUTH_CLIENT_ID -使用以下命令生成
• OAUTH_CLIENT_SECRET -使用以下命令生成
• BASE_URL -您的公共MCP服务器URL
• PANGOLIN_ENDPOINT -您的穿山甲服务器
• NEWT_ID 和 NEWT_SECRET -从穿山甲隧道

3.生成OAuth凭据

# Generate SECRET_KEY
python3 -c "import secrets; print('OAUTH_SECRET_KEY=' + secrets.token_urlsafe(32))"

# Generate CLIENT_ID
python3 -c "import secrets; print('OAUTH_CLIENT_ID=openproject-mcp-' + secrets.token_hex(8))"

# Generate CLIENT_SECRET
python3 -c "import secrets; print('OAUTH_CLIENT_SECRET=' + secrets.token_urlsafe(32))"

将这些值复制到您的 .env 文件。

4.获取OpenProject API代币

1. 登录到您的OpenProject实例
2. 首选 我的账户 → 访问令牌
3. 点击 API
4. 复制40个字符的令牌
5. 添加到 .env 作为 OPENPROJECT_API_KEY

5.配置穿山甲（如果使用）

1. 在Pangolin为您的域名创建一个新网站
2. 创建新的Newt隧道
3. 复制 NEWT_ID 和 NEWT_SECRET 到 .env
4. 配置路由：

- 路径： / （根） - 目标： oauth-wrapper:8080

6.部署

# Build and start containers
docker compose up -d --build

# Check logs
docker compose logs -f

# Verify health
curl http://localhost:8080/health
# Or via your public URL:
curl https://your-domain.com/health

7.配置克劳德自定义连接器

在克劳德：

1. 创建新 自定义连接器
2. 名字：OpenProject MCP
3. 基本URL：您的 BASE_URL 从 .env
4. 认证：OAuth 2.0
5. OAuth设置:

- 授权URL: {BASE_URL}/oauth/authorize - 令牌URL: {BASE_URL}/oauth/token - 客户端ID：您的 OAUTH_CLIENT_ID - 客户端密钥：您的 OAUTH_CLIENT_SECRET - 范围: api （可选）

1. 端点:

- 添加端点： GET /sse （SSE流）

8.测试

连接后，在Claude中尝试：

List all my OpenProject projects

Create a new project called "Test Project"

Show me available work package types

环境变量引用

必需

可选的

项目结构

.
├── docker-compose.yml        # Container orchestration
├── Dockerfile.oauth          # OAuth wrapper container
├── oauth_mcp_wrapper.py      # OAuth authentication layer
├── .env.example             # Environment template
└── README.md                # This file

安全最佳实践

1. 保持 .env 安全 -永远不要提交到公共存储库
2. 使用强大的秘密 -生成方式 secrets.token_urlsafe(32)
3. 启用HTTPS -使用Pangolin或SSL反向代理
4. 轮换凭据 -定期更新OAuth机密和API令牌
5. 监控访问 -检查日志中是否有未经授权的尝试
6. 限制权限 -使用最少特权的OpenProject API令牌

故障排除

容器无法启动

# Check logs
docker compose logs oauth-wrapper
docker compose logs openproject-mcp-server

# Verify environment variables
docker compose config

无法通过公共URL访问

# Test locally first
curl http://localhost:8080/health

# Check Pangolin tunnel
docker compose logs mcp-oauth-newt

# Verify DNS
nslookup your-domain.com

OAuth身份验证失败

# Verify OAuth endpoints
curl https://your-domain.com/.well-known/oauth-authorization-server

# Check credentials match in both .env and Claude config
# Ensure OAUTH_REDIRECT_URI matches Claude's callback URL

MCP服务器无法连接到OpenProject

# Test API token
docker compose exec openproject-mcp-server curl -H "Authorization: Bearer YOUR_API_KEY" \
  https://your-openproject.com/api/v3/projects

# Check OpenProject URL is accessible from container
docker compose exec openproject-mcp-server ping your-openproject-domain

可用的MCP工具

连接后，Claude可以使用这些工具：

• openproject:create_project -创建新项目
• openproject:get_projects -列出所有项目
• openproject:create_work_package -创建工作包
• openproject:get_work_packages -列出工作包
• openproject:update_work_package -更新工作包
• openproject:create_work_package_dependency -创建依赖关系
• openproject:get_users -列出用户
• openproject:assign_work_package_by_email -分配工作包
• openproject:get_project_summary -获取项目概述
• 还有更多。..

贡献

欢迎投稿！拜托：

1. 分叉存储库
2. 创建要素分支
3. 进行更改
4. 彻底测试
5. 提交拉取请求

许可证

此项目按原样提供，用于OpenProject和Claude AI。

支持

对于问题和疑问：

1. 检查故障排除部分
2. 查看容器日志
3. 验证所有环境变量
4. 分别测试每个组件

鸣谢

• 建立在 firsthalfhero/openproject mcp服务器
• 用途 快速API 用于OAuth包装器
• 兼容 穿山甲 隧道效应
• 专为 克劳德·艾 整合

版本

当前版本：1.0.0

适用于：

• OpenProject 16.5+
• Claude AI与自定义连接器
• MCP协议2025-06-18