openproject-local-mcp

OpenProject API v3をMCPツールとして公開するローカルSTDIOサーバーです。Codex CLIやGitHub Copilot CLIなどのMCPクライアントから、プロジェクトとWork Packageを参照できます。

方針

• OpenProjectは直接クラウド側へ公開せず、開発者PC上のローカルMCPサーバーからAPI v3へ接続します。
• APIトークンは専用ユーザーの最小権限トークンを使います。
• 初期状態では読み取り中心です。create_work_packageとadd_work_package_commentはOPENPROJECT_ENABLE_WRITE=trueの場合だけ動きます。
• OpenProject固有の名称、HAL+JSON、フィルター形式をそのまま扱います。

機能

• プロジェクト一覧
• Work Packageの検索、詳細取得、自分の担当項目の取得
• 明示的に有効化した場合のみ、Work Package作成とコメント追加
• Bearer認証（標準）とAPIトークンのBasic認証

セットアップ

npm install
npm run build

.env.exampleを参考に、MCPクライアントから環境変数を渡してください。.envはローカル開発専用で、Gitへコミットしないでください。

OPENPROJECT_URL=https://openproject.example.local
OPENPROJECT_API_TOKEN=xxxxxxxxxxxxxxxx
OPENPROJECT_AUTH_MODE=bearer
OPENPROJECT_ENABLE_WRITE=false

OPENPROJECT_URLにはインスタンスのルートURLを指定します。/api/v3は付けません。現行OpenProjectではAPIトークンをBearerまたはBasic認証で利用できます。既定値はbearerです。

MCPクライアント設定

Codex CLI

[mcp_servers.openproject]
command = "node"
args = ["/path/to/openproject-local-mcp/dist/index.js"]
default_tools_approval_mode = "prompt"

[mcp_servers.openproject.env]
OPENPROJECT_URL = "https://openproject.example.local"
OPENPROJECT_API_TOKEN = "xxxxxxxxxxxxxxxx"
OPENPROJECT_AUTH_MODE = "bearer"
OPENPROJECT_ENABLE_WRITE = "false"

GitHub Copilot CLI

copilot mcp add openproject \
  --env OPENPROJECT_URL=https://openproject.example.local \
  --env OPENPROJECT_API_TOKEN=xxxxxxxxxxxxxxxx \
  --env OPENPROJECT_ENABLE_WRITE=false \
  -- node /path/to/openproject-local-mcp/dist/index.js

提供ツール

• list_projects: APIユーザーから見えるプロジェクト一覧
• search_work_packages: 一般的な条件またはAPI v3のカスタムフィルターによる検索
• get_work_package: 数値IDによる詳細取得
• get_my_work_packages: APIユーザーに割り当てられたWork Package
• create_work_package: Work Package作成（書き込みの明示許可が必要）
• add_work_package_comment: コメント追加（書き込みの明示許可が必要）

Agent Skill

OpenProject MCPの使い分けと書き込み時の確認ルールをagent-skills/openproject-workflows/SKILL.mdに同梱しています。利用するエージェント環境の個人用Skillsディレクトリへ手動でコピーしてください。SkillにはAPIトークンや実URLを含めないでください。

OpenProjectのoffsetは件数ではなく、1から始まるページ番号です。custom_filtersは次の形式で指定できます。

[
  {
    "name": "status",
    "operator": "=",
    "values": ["5"]
  }
]

書き込み系を有効にする

OPENPROJECT_ENABLE_WRITE=true

create_work_packageでは、OpenProjectが作成時に必要とするproject_id、type_id、subjectを必須にしています。

{
  "project_id": 3,
  "type_id": 1,
  "subject": "ログイン画面のエラーを確認する",
  "description": "再現手順と期待結果を整理する。"
}

コメント追加例:

{
  "id": 1234,
  "comment": "調査を開始しました。再現条件を確認中です。"
}

開発

npm run typecheck
npm run build
npm test

テストではHTTP通信をモックし、実OpenProjectには接続しません。

セキュリティ

• APIトークンは専用ユーザーの最小権限トークンを利用してください。
• .envや実URLを含むMCPクライアント設定をコミットしないでください。
• 書き込みツールはOPENPROJECT_ENABLE_WRITE=trueを明示した場合だけ有効です。
• OpenProjectのAPIがHTTPSで利用できる環境ではHTTPSを使用してください。

詳細は設計メモを参照してください。

OpenProject API仕様:

• API v3 Introduction
• Projects endpoint
• Work Packages endpoint
• Filters

ライセンス

MIT License