AI导哈

OpenProject MCP服务器

一个生产就绪的Model Context Protocol (MCP)服务器，支持OAuth 2.0认证，用于OpenProject与Claude AI等MCP客户端的集成。

  • by intositeme
  • Python
  • 本地部署
  • 更新于
在 GitHub 查看 intositeme/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 （可选）
  6. 端点:
    • 添加端点： GET /sse （SSE流）

8.测试

连接后，在Claude中尝试：

List all my OpenProject projects

Create a new project called "Test Project"

Show me available work package types

环境变量引用

必需

变量 描述 示例
OPENPROJECT_URL 您的OpenProject实例 https://openproject.example.com
OPENPROJECT_API_KEY OpenProject API令牌 abc123... （40个字符）
OAUTH_SECRET_KEY JWT签名密钥 生成的随机字符串
OAUTH_CLIENT_ID OAuth客户端标识符 openproject-mcp-abc123
OAUTH_CLIENT_SECRET OAuth客户端机密 生成的随机字符串
BASE_URL 公共MCP服务器URL https://mcp.example.com
PANGOLIN_ENDPOINT 穿山甲服务器URL https://pangolin.example.com
PANGOLIN_IP 穿山甲服务器IP 192.168.1.100
NEWT_ID 穿山甲隧道ID 来自穿山甲
NEWT_SECRET 穿山甲隧道秘密 来自穿山甲

可选的

变量 默认值 描述
OAUTH_REDIRECT_URI https://claude.ai/oauth/callback OAuth回调
MCP_LOG_LEVEL INFO 日志级别
CACHE_TIMEOUT 5 缓存超时（分钟）
PAGINATION_SIZE 100 API页码大小
MAX_RETRIES 3 API重试次数
DATA_PATH ./data 数据存储路径

项目结构

.
├── 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. 分别测试每个组件

鸣谢

版本

当前版本：1.0.0

适用于：

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

相关 MCP