OpenProject CE

OpenProject CE MCP

ローカルの AI エージェントが、構造化され保護されたツールを通じてプロジェクトデータを読み取り、管理できる OpenProject 用 MCP サーバーです。

このサーバーは、stdio 経由で MCP クライアントのローカルサブプロセスとして動作します。OpenProject API v3 をラップし、プロジェクト、作業パッケージ、メンバーシップ、バージョン、ボード、会議、時間エントリーなどを操作する型付きツールを公開します。

PyPI でこのページをご覧ですか？ 以下のリンクはすべて GitHub リポジトリを参照しています — docs/ のページと画像は Git リポジトリおよびソース配布物に含まれており、 インストール済みパッケージ自体には含まれていません。

この MCP を使う理由

• コンテキスト消費を抑える設計 — 生の HAL ペイロード（生 API では各項目あたり約 21 フィールドと約 46 個のリンク）ではなく、エージェント向けのコンパクトなレスポンスを返します。select を使ったレスポンスごとのトークン数を最大 −99% 削減できることを測定しています。詳しい数値はコンテキスト効率をご覧ください。
• 保護された書き込み — すべての書き込み操作でプレビューしてから確定するパターンを採用しています。これを回避する方法はありません。
• 多層防御によるプロジェクト範囲制限 — MCP の読み取り／書き込み許可リストにより、OpenProject 独自のサーバー側権限に加えて、トークンの実効範囲を制限します。
• 生の REST クライアントではなく、型付きツール — 手作業で HAL リクエストを構築してリンクをたどる代わりに、意図（一覧表示、検索、作成、更新）ごとに 1 回の呼び出しで操作できます。

---

できること

プロジェクト

• プロジェクトの一覧表示、作成、コピー、更新、削除
• プロジェクトの設定、ライフサイクルのフェーズ、管理コンテキストの読み取り
• メンバーシップとバージョンの作成、更新、削除、役割の一覧表示

作業パッケージ

• 構造化フィルターを使った作業パッケージの一覧表示と検索
• 作業パッケージの作成、更新、削除、サブタスクの作成、関連の作成・更新・削除、コメントの追加（編集と削除は不可）
• 添付ファイルのアップロード、読み取り（画像とテキストはモデルにインラインで渡されます）、削除、ウォッチャーの追加と削除、アクティビティログの読み取り
• 時間エントリーの記録、更新、削除

ボードとビュー

• 保存済みボード（クエリ）の作成、読み取り、更新、削除、ビューの読み取り

会議

• アジェンダ項目、セクション、成果を含む会議の作成、読み取り、更新、削除
• 定期会議の管理：シリーズの作成、更新、削除、開催回の一覧表示、単一の開催回の初期化またはキャンセル

管理とスケジュール（オプトイン）

• ユーザーアカウントとグループメンバーシップの読み取り
• ユーザーの作成、更新、ロック、ロック解除、削除、グループメンバーの追加と削除
• ファイルストレージ接続（Nextcloud など）の読み取りと管理
• ユーザーの非稼働時間と勤務時間の読み取りと管理

補助データ

• ID を指定した個別の Wiki ページの取得、ニュースの作成、更新、削除、ドキュメントの読み取りと更新
• 通知の読み取りと既読化、ヘルプテキスト、稼働日、インスタンス設定の読み取り
• グリッドの作成と確認、カスタムオプションの確認

すべての書き込み操作では、プレビューしてから確定するパターンを採用しています。ツールを 1 回呼び出して検証済みのプレビューを取得し、その後 confirm=true を指定して再度呼び出すと実行されます。これを回避する方法はありません。

---

対象範囲：コミュニティ版

この MCP サーバーは、OpenProject Community Edition のみを対象としています。以下のような Enterprise Edition の機能には対応していません。

• プレースホルダーユーザー
• ポートフォリオ
• プログラム
• カスタムアクション
• ベースライン比較

注： OpenProject Enterprise Edition には、独自の MCP サーバーが含まれています。Enterprise ライセンスをお持ちの場合は、この MCP サーバーではなく、公式の Enterprise MCP を使用してください。

---

仕組み

• MCP クライアントと stdio 経由で通信します。リモートサーバーも永続ストレージもありません
• コアの読み取りグループ（プロジェクト、作業パッケージ、メンバーシップ、バージョン、ボード、ミーティング）はデフォルトで有効ですが、OPENPROJECT_READ_PROJECTS にプロジェクトを指定するまでは、list_statuses、list_types、get_current_user など、プロジェクトに依存しないツールのみが登録されます。個人用、管理者用、ユーザースケジュール用、拡張メタデータ用のツールはオプトイン方式です
• プロジェクトスコープの書き込みカテゴリはデフォルトで有効ですが、ツールが登録されるのは、OPENPROJECT_READ_PROJECTS と OPENPROJECT_WRITE_PROJECTS の両方にプロジェクトが指定されている場合のみです。また、書き込み先は両方に含まれるプロジェクトに限られます。実際の制限となるのはカテゴリフラグではなく、許可リストです。個人データ、管理者用、ユーザースケジュール用の書き込みはオプトイン方式です
• 作成・更新操作では、書き込み前に OpenProject のフォームエンドポイントに対してペイロードを検証します。削除などのシンプルな操作は、確認後に直接実行します
• プロジェクトスコープはサーバー側で適用されます。MCP が公開するのは、設定された許可リストで許可された項目のみです
• 応答には上限があり、ページネーションされます。生の HAL ペイロードではなく、簡潔な要約を返します

OpenProject REST API を直接呼び出すのではなく、この MCP を使う主な理由の一つは、生の HAL ペイロードではなく、コンテキスト効率に優れた応答を返すことです。これは一覧表示だけに限りません。以下の数値は、代表的な 3 件の作業パッケージを対象に測定したものです（bytes/4 による概算ではなく、実際の tiktoken のカウントです）。読み取り、検索、書き込み、バッチの各呼び出しはすべて、同じ −85%～−98% の範囲に収まります。呼び出しタイプごとの詳細、ツールカタログのサイズ、測定方法については、コンテキスト効率を参照してください。

応答	トークン数	生の API との比較
OpenProject REST API v3 の生データ（HAL）	~9,992	基準
list_work_packages（MCP）	~861	−91%
select を指定した list_work_packages（5 フィールド）	~174	−98%

---

インストール

このクイックスタートには pipx が必要です。まだインストールされていない場合は、インストールを参照してください。

pipx install openproject-ce-mcp
openproject-ce-mcp configure
openproject-ce-mcp --version

すでに uv を使用している場合も、uv tool install openproject-ce-mcp で同じようにインストールできます。 通常の pip install が適しているケースや、インストールせずに必要なときだけ実行できる代替手段 uvx については、インストールを参照してください。

configure は OpenProject の URL、API トークン、プロジェクトスコープを収集し、選択した MCP クライアント用の設定を書き込みます。プロジェクトスコープを指定する方法を推奨します。この場合、サーバーは現在のプロジェクトでのみ利用できます。グローバルに設定すると、どこからでも利用できるようになります。その後、MCP クライアントを再起動し、get_current_user または list_projects を呼び出すよう指示して、動作を確認してください。

要件、更新、ソースからのインストール、アンインストールについてはインストールを、クライアントごとのセットアップガイドについてはクライアントを参照してください。

---

ドキュメント

ドキュメント全文は docs/ にあります。ドキュメントハブからご覧ください。

• セットアップ： インストール · クライアント · 設定 · トラブルシューティング
• ツールの使用： ツールリファレンス · 作業パッケージのフィルター · フィールドの非表示
• クライアントガイド： Claude / Claude Code · Claude Desktop · Codex · Cursor · VS Code / GitHub Copilot
• コントリビューション： 開発 · アーキテクチャ · コンテキスト効率

---

設定の要点

クライアント設定（.mcp.json、.codex/config.toml、または .vscode/mcp.json）には API トークンが含まれます。パスワードと同様に扱い、バージョン管理に含めないでください。具体的な .gitignore の手順については、クライアントからお使いのクライアントに対応するガイドを選んでください。configure が書き込むのは最小限の設定、つまり安全なデフォルト値と異なる値だけです。コアの読み取りグループとプロジェクト単位の書き込みカテゴリはデフォルトで有効ですが、それらのプロジェクトに紐づくツールが登録され、プロジェクトへのアクセスが許可されるのは、OPENPROJECT_READ_PROJECTS にプロジェクトを指定した場合のみです（書き込みの場合は OPENPROJECT_WRITE_PROJECTS にも指定する必要があります）。実際の制御を行うのはカテゴリのフラグではなく、この 2 つの許可リストです。

環境変数の全項目と、configure --quick と --advanced で尋ねられる内容については、設定をご覧ください。

---

セキュリティ

プロンプトインジェクション

ユーザーが提供するテキスト（作業パッケージの説明、コメント、ニュース、Wiki コンテンツ）には <user-content> タグが付けられ、信頼できないものとしてサーバーの指示に明記されます。エージェントはこのコンテンツを指示ではなくデータとして扱う必要があります。

プロンプトインジェクションへの対策、報告手順、サポート対象バージョンを含むセキュリティモデルの詳細については、SECURITY.mdをご覧ください。

---

質問とバグ報告

質問は GitHub Discussions でお寄せください。 バグの報告や機能のリクエストは GitHub Issues からお願いします。 セキュリティの脆弱性は、SECURITY.md の記載に従って非公開で報告してください。

---

開発

main は最新リリースの凍結スナップショットであり、現在の開発ブランチではありません。クローンするブランチ（現在の開発用かバグ修正用か）と、テストスイート全体（ユニットテスト、インテグレーションテスト、Docker テストインスタンス）については、CONTRIBUTING.mdをご覧ください。

---

ライセンス

MIT — LICENSE をご覧ください。プロジェクト全体は単一のトップレベルのライセンスファイルでカバーされています。MIT ライセンスの Python パッケージで一般的な慣例に従い、個々のソースファイルにはファイルごとの著作権ヘッダーを付けていません。