OpenProject MCP Server

ClaudeをOpenProjectインスタンスに接続するための高品質な**Model Context Protocol (MCP)**サーバーです。Claudeが会話から直接、プロジェクト、ワークパッケージ、ユーザー、タイムエントリーを照会・検索・管理できるようにします。

🚀 特徴

✅ プロジェクトアクセス - プロジェクトの一覧表示、フィルタリング、詳細取得
✅ ワークパッケージ管理 - 高度なフィルタリングによるタスク、バグ、機能の表示
✅ 全文検索 - コンテンツによるワークパッケージの検索
✅ アクティビティ履歴 - ワークパッケージの変更とコメントの表示
✅ ユーザー管理 - ユーザーの一覧表示と情報取得
✅ タイムエントリー - プロジェクト、ユーザー、期間ごとの登録時間の照会
✅ スマートページネーション - 大規模データセットのサポート
✅ 堅牢なエラーハンドリング - 明確で実用的なメッセージ
✅ 完全な型付け - 最大限の型安全性を実現するTypeScript

Related MCP server: OpenProject MCP Server

📋 前提条件

• Node.js 18+ または Bun 1.0+

• APIアクセスが可能なOpenProject 13+ インスタンス

• OpenProjectのAPIトークン（設定で生成可能）

🔧 インストール

1. サーバーをクローンまたはダウンロード

cd openproject-mcp-server

2. 依存関係をインストール

npm install
# o con bun
bun install

3. 環境変数の設定

.env.example を .env にコピーして値を入力します：

cp .env.example .env

.env を編集します：

OPENPROJECT_URL=https://openproject.empresa.com
OPENPROJECT_API_TOKEN=tu-token-api-aqui
OPENPROJECT_PAGE_SIZE=50

OpenProjectでAPIトークンを生成する方法：

1. OpenProjectで Administration → API & Webhooks → Personal Access Tokens に移動します

2. "+ New Personal Access Token" をクリックします

3. わかりやすい名前を付けます（例：「Claude MCP」）

4. 必要な権限をチェックします：

   • ✅ view_work_packages

   • ✅ view_projects

   • ✅ view_users

   • ✅ view_time_entries

   • ✅ edit_work_packages（作成・編集する場合）

5. 生成されたトークンを .env にコピーします

4. サーバーをコンパイル

npm run build

🎯 使用方法

オプションA: Claude Codeで使用

1. Claude Codeを開きます

2. Settings → MCP Servers に移動します

3. + Add Local Server をクリックします

4. 設定します：

   • Name: openproject

   • Command: node

   • Arguments: ["path/to/openproject-mcp-server/dist/index.js"]

   • Environment Variables: .env の値

5. 保存してClaudeに再接続します

オプションB: テスト用にローカルで実行

npm run dev

次に、別のターミナルでMCP Inspectorを使用します：

npm run inspect

これにより、各ツールをテストできるWebインターフェースが開きます。

オプションC: Claude.aiで

1. claude.ai/code を開きます

2. Settings → MCP Servers に移動します

3. このサーバーをアクセス可能なホストにデプロイした場合は、リモートサーバーを追加します

4. アクセス資格情報を設定します

🛠️ 利用可能なツール

📦 プロジェクト

list_projects

オプションのフィルタリングで全プロジェクトを一覧表示します。

パラメータ：

• offset (number, optional): ページネーション用

• name_filter (string, optional): 名前でフィルタリング

• status (enum: "active" | "archived", optional): ステータスでフィルタリング

例：

Claude: List all active projects
→ OpenProject: Muestra proyectos activos

get_project

プロジェクトの完全な詳細を取得します。

パラメータ：

• project_id (string | number): プロジェクトのIDまたは識別子

📋 ワークパッケージ（タスク）

list_work_packages

高度なフィルタリングでワークパッケージを一覧表示します。

パラメータ：

• project_id (string | number, optional): プロジェクトでフィルタリング

• status (string, optional): ステータス（例：「Open」「In Progress」）

• priority (string, optional): 優先度

• assignee_id (number, optional): 担当ユーザー

• search (string, optional): テキスト検索

• offset (number, optional): ページネーション

get_work_package

ワークパッケージの完全な詳細を取得します。

パラメータ：

• work_package_id (number): ワークパッケージのID

get_work_package_activities

変更履歴とコメントを取得します。

パラメータ：

• work_package_id (number): ワークパッケージのID

search_work_packages

ワークパッケージの全文検索。

パラメータ：

• query (string, required): 検索語

• project_id (string | number, optional): プロジェクトに限定

• status (string, optional): ステータスでフィルタリング

• priority (string, optional): 優先度でフィルタリング

👤 ユーザー

list_users

OpenProject内の全ユーザーを一覧表示します。

パラメータ：

• offset (number, optional): ページネーション

get_user

特定のユーザーの詳細を取得します。

パラメータ：

• user_id (number): ユーザーのID

⏱️ タイムエントリー

list_time_entries

期間、ユーザー、プロジェクトによるフィルタリングでタイムエントリーを一覧表示します。

パラメータ：

• work_package_id (number, optional): ワークパッケージでフィルタリング

• user_id (number, optional): ユーザーでフィルタリング

• project_id (string | number, optional): プロジェクトでフィルタリング

• from_date (string, optional): 開始日（YYYY-MM-DD）

• to_date (string, optional): 終了日（YYYY-MM-DD）

• offset (number, optional): ページネーション

get_time_entry

タイムエントリーの詳細を取得します。

パラメータ：

• time_entry_id (number): タイムエントリーのID

✍️ 書き込み（エピックとユーザーストーリーの作成）

list_project_types

プロジェクトで利用可能なワークパッケージタイプ（Epic、User Story、Task、Bugなど）をID付きで一覧表示します。最初にこれを使用してください — タイプIDはOpenProjectのインスタンスによって異なります。

パラメータ：

• project_id (string | number): プロジェクトのIDまたは識別子

create_work_package

ワークパッケージ（エピック、ユーザーストーリー、タスクなど）を作成します。parent_id を使用して、ユーザーストーリーを対応するエピックの下に配置します。

パラメータ：

• project_id (string | number)

• subject (string)

• description (string, optional, Markdown)

• type_id (number, optional): list_project_types で取得したタイプのID

• parent_id (number, optional): 親エピックのID

• priority_id、assignee_id、start_date、due_date (optional)

create_work_packages_bulk

複数のワークパッケージを1回の呼び出しで作成します（Wordから抽出したすべてのユーザーストーリーをアップロードするのに最適です）。各アイテムは独自の parent_id を持つことができるため、異なるエピックのストーリーを同じ呼び出しで作成できます。アイテムごとにレポート（成功/エラー）を返し、1つが失敗してもバッチ全体を中止しません。

パラメータ：

• project_id (string | number)

• items (array, 最大100): 各アイテムは create_work_package と同じフィールド（project_id を除く）を持ちます

📋 フロー: Wordからエピックとユーザーストーリーをアップロード

チームの典型的なユースケース：.docx で作成されたユーザーストーリーがあり、エピック → ストーリーの関係を維持しながらOpenProjectにアップロードする必要があります。

1. 個人用APIトークンを生成（各開発者が自分のものを使います。上記参照）し、ローカルの .env を設定します。

2. Claudeとの会話を開き、エピック/ストーリーを含む .docx ファイルを添付または参照します（Claudeは直接読むことができます）。

3. Claudeに依頼します：「このWordを読んで、エピックとそのユーザーストーリーを特定し、OpenProjectのプロジェクトXにアップロードして」。

4. Claudeは通常、手動でオーケストレーションしなくても次のことを行います：

   • プロジェクトに対して list_project_types を実行し、EpicとUser Storyの type_id を確認します。

   • 各エピックに対して create_work_package を実行します（数が少ないため、IDを取得するために1つずつ実行します）。

   • ユーザーストーリーに対して create_work_packages_bulk を実行し、各ストーリーに対応するエピックの parent_id を使用します。

5. 最終レポート（何が作成され、何が失敗したか）を確認し、必要に応じてOpenProjectで修正します。

注：トークンには、読み取りだけでなく作成を行うために edit_work_packages 権限が必要です（トークン生成のセクションを参照）。

📊 ユースケース

1. プロジェクト分析

Claude: "Análiza todos los proyectos activos y resume cuáles tienen más work packages abiertos"
→ El servidor lista proyectos, luego itera para contar paquetes abiertos

2. タスク検索

Claude: "Busca todas las tareas sobre 'API' en estado 'In Progress' del proyecto BACKEND"
→ search_work_packages con query="API", status="In Progress", project_id="BACKEND"

3. タイムレポート

Claude: "¿Cuántas horas registró Juan en la última semana?"
→ list_time_entries con user_id=juan, from_date=última_semana

4. プロジェクトの状態

Claude: "Dame un resumen del proyecto FRONTEND: qué se completó, qué está en progreso y qué sigue"
→ get_project + list_work_packages con diferentes status

5. 変更の監査

Claude: "¿Quién cambió el estado del work package #123 y cuándo?"
→ get_work_package_activities para ver el historial

🏗️ アーキテクチャ

src/
├── index.ts                 # Entry point del servidor MCP
├── client/
│   └── openproject.ts       # Cliente HTTP para OpenProject API
├── tools.ts                 # Registro e implementación de herramientas
├── schemas/
│   └── index.ts             # Validación Zod de inputs
└── utils/
    └── formatters.ts        # Formatos de salida Markdown

🔐 セキュリティ

• ✅ Bearer Token認証（安全で、平文の資格情報を必要としません）

• ✅ Zodによる入力検証（インジェクションを防止）

• ✅ 詳細なエラーハンドリング（機密データを公開しません）

• ✅ TypeScript strict mode（型エラーを防止）

• ⚠️ トークンは .env に保存されます - このファイルをgitにコミットしないでください

🚨 トラブルシューティング

「Authentication failed」

• .env 内のトークンが有効であることを確認します

• OpenProjectで新しいトークンを再生成します

「Connection error」

• OPENPROJECT_URL がマシンからアクセス可能であることを確認します

• プロキシ/VPNを使用している場合は、プロキシの環境変数を設定します

「No projects found」

• ユーザーにプロジェクトを表示する権限があることを確認します

• インスタンスにプロジェクトが存在することを確認します

サーバーが起動しない

npm run build
npm run dev

ターミナルのエラー出力を確認してください。

📈 今後の改善予定

• Claudeからのワークパッケージ作成・編集のサポート

• ワークパッケージへのコメントのサポート

• ガントチャートとの統合

• リアルタイム通知のためのWebhooks

• パフォーマンス向上のためのデータキャッシュ

• 総合的な評価（SEP）

📦 開発チームへの配布

各開発者には自分のコピー + 自分のAPIトークンが必要です（複数人でトークンを共有しないでください — OpenProjectではアクションがユーザーごとに監査されます）。

推奨オプション: 共有Gitリポジトリ

1. このフォルダをプライベートリポジトリ（GitHub orgまたは linux.ie のGitea/GitLab）にアップロードします。.env はすでに .gitignore に含まれていることを忘れないでください — 決してアップロードされません。

2. 各開発者：

   git clone <url-del-repo>
   cd openproject-mcp-server
   npm install
   npm run build
   cp .env.example .env

3. 各開発者が自分のトークンを生成し（Administration → API & Webhooks → Personal Access Tokens、ストーリーを作成する場合は edit_work_packages 権限付き）、自分の .env に貼り付けます。

4. 各開発者がClaude Code（Settings → MCP Servers → Add Local Server）でローカルの dist/index.js を指定して追加します。

Gitを使わない代替案: 圧縮フォルダ

まだリポジトリを構築したくない場合は、フォルダの .zip（node_modules、dist、.env を除く）を共有し、各開発者がローカルで npm install && npm run build を実行できます。仕組みは同じで、配布手段が変わるだけです — デプロイする中央サーバーがないためCI/CDは不要です：MCPは各開発者のマシンで stdio 上で実行されます。

後で共有リモートサーバーとして実行する場合

各開発者がローカルで実行する代わりに、全員が利用する単一のサーバー（例：linux.ie）を希望する場合は、CI/CD（プッシュごとのビルド+デプロイ）が適用され、トランスポートを stdio からHTTPに移行する必要があります。これは大きなアーキテクチャの変更です — その方針を希望する場合はお知らせください。別途計画します。

🤝 コントリビューション

これはオープンソースのMCPサーバーです。改善するには：

1. リポジトリをフォークします

2. 機能用のブランチを作成します（git checkout -b feature/mi-feature）

3. 変更をコミットします（git commit -am 'Agrego mi-feature'）

4. ブランチにプッシュします（git push origin feature/mi-feature）

5. プルリクエストを開きます

📄 ライセンス

MIT - 自由に使用、変更、配布できます

💬 サポート

バグの報告、質問、提案は：

• リポジトリでissueを開く

• MCPドキュメント を参照

• OpenProject APIドキュメント を確認

Integral de Empaques S.A.S.のために❤️を込めて作成