OpenProject

OpenProject MCP Server

OpenProject API v3 用の MCP（Model Context Protocol）サーバーです。Claude やほかの MCP クライアントに、作業パッケージ、コメントと関連、添付ファイル、git／PR のアクティビティ、プロジェクト、保存済みクエリ、通知、時間記録、バージョン、ユーザーとメンバーシップ、会議、ニュース、ドキュメント、予算、レポート作成を網羅する 91 個のツールと、4 個のレポート／ワークフロー用プロンプト、3 個のリソーステンプレートを提供します。FastMCP 3.x と httpx（HTTP/2）を基盤としています。

このプロジェクトは、OpenProject の Community エディションを対象としています。OpenProject の Enterprise エディションには、現在、独自の組み込み MCP 統合が付属しています。このサーバーは、セルフホストの Community インスタンスに同じ機能を提供します。公開 API v3 だけを必要とするため、どのエディションでも問題なく動作します。

設計原則はすべてコードで徹底されています。

• すべてを構造化。 すべてのツールが型付きモデルを返すため、クライアントは文章ではなく、outputSchema と機械可読な structuredContent を受け取ります。エラーは、安定した type、上流の http_status、message、呼び出しを修正する方法を示す hint を含む JSON エンベロープとして返されます。
• 正直な機能縮退。 OpenProject のインスタンスによって、バージョン、インストール済みモジュール、権限が異なります。ツールは、取得できなかった情報をインバンドの注記として報告します。モジュールがない場合は、成功を装ったり、トレースバックだけを返したりせず、説明付きの空のページを返します。
• デフォルトで安全。 読み取り専用モード、管理者権限が必要なメンバーシップの書き込み、グループごとのツール無効化、すべての破壊的なツールに対する confirm=true ガード、常時検証される TLS、ログに記録されることのない認証情報を備えています。
• バージョンに適応。 OpenProject 14 LTS から 17.x を対象としています。API の違いは、前提に頼らず、遅延実行されてキャッシュされる機能プローブで検出します（サポート対象の OpenProject バージョンを参照）。

動作例

架空の「ウェブサイトリニューアル」プロジェクトとの 2 回のやり取りです。以下の ID、名前、日付はすべて架空のものです。期待する結果を説明すると、モデルがツールを選び、文章を再解析する必要のない型付きオブジェクトが返されます。

You         What is still open in Website Relaunch and due by Friday? The checkout
            bug is urgent — raise it and leave a note for whoever owns it.

  →  list_work_packages(project="website-relaunch", status_scope="open",
                        due_before="2026-03-13", sort_by=[["due_date", "asc"]])

     { "items": [
         { "id": 4821, "subject": "Checkout fails on expired coupon codes",
           "type": {"id": 7, "name": "Bug"}, "status": {"id": 7, "name": "In progress"},
           "assignee": {"id": 118, "name": "Dana Okafor"}, "due_date": "2026-03-11" },
         { "id": 4830, "subject": "Move press-kit assets to the new CDN",
           "type": {"id": 1, "name": "Task"}, "status": {"id": 1, "name": "New"},
           "assignee": null, "due_date": "2026-03-13" }],
       "pagination": {"total": 2, "page": 1, "page_size": 20, "has_more": false} }

  →  update_work_package(id=4821, priority="High")
  →  add_work_package_comment(id=4821, comment="Raised to High — it blocks the
                              launch checklist. Dana, can you take a look today?")

Assistant   Two open items are due by Friday. #4821 is High now and the note is on
            its thread; #4830 is due Friday and still has nobody on it.

上の行は一部を省略しています。各行には priority、project、start_date、percentage_done、updated_at も含まれ、エンベロープには、それらを埋める呼び出しに備えて groups、sums、notes の各スロットも用意されています。

プロンプトテンプレートを使うと、ツールとの往復を省けます。サーバーが OpenProject から直接情報を読み取り、取得方法を指示するのではなく、完成したドキュメントを返します。返されるドキュメントには、数値はすでに計算済みであり、再計算したり、脚色したりしてはならないという注記が付いています。

You         /weekly_report project=website-relaunch

            # WEEKLY REPORT - AGILE SCRUM

            _Generated from live OpenProject data_
            ...
            ## B. EXECUTIVE SUMMARY

            **Progress against the sprint goal:** Not assessed — sprint goal and completion dates are not available

            **Currently closed work updated in the window:**
            1. #4802 - Ship the new pricing page
            2. #4795 - Halve the hero image payload
            ...
            ### Data notes

            - open/closed bucketing uses each status's isClosed flag from
              GET /statuses, not status names; a status this instance renamed
              or translated is still bucketed correctly

最後のブロックは、このサーバーの基本方針を示しています。レポートでは、どの数値が一部のデータに基づくものかを示し、情報を読み取れなかったツールは推測せず、その不足を注記として返します。機能の全体はツールとプロンプトとリソースにまとめられています。

要件

• Python >= 3.12
• OpenProject のインスタンス（バージョン 14 LTS から 17.x。どのエディションでも利用できますが、Community を対象としています。Enterprise には独自の MCP 統合が付属します）
• OpenProject API キー：OpenProject で マイアカウント → アクセストークン に移動し、API トークンを生成します

インストール

配布名は openproject-mcp-server です。同一のコンソールスクリプト openproject-mcp-server と openproject-mcp が2つインストールされます。長いほうが正式名称です（無関係な PyPI パッケージも openproject-mcp という名前の実行ファイルをインストールします）。

インストール手順なしで、uv を使って1回だけ実行します。

uvx openproject-mcp-server

または、継続して使用できるようにインストールします。

uv tool install openproject-mcp-server
# or
pip install openproject-mcp-server

最小限の設定には、2つの環境変数が必要です。

export OPENPROJECT_URL=https://openproject.example.com
export OPENPROJECT_API_KEY=your-api-key

サーバーを起動せずに設定を検証します。

openproject-mcp-server --check

--check は設定を検証して終了します。インスタンスには接続しません。クライアント経由で接続したら、get_instance_info ツールを呼び出して、ライブのエンドツーエンドチェックを実行してください。設定が不足しているか無効な場合、サーバーは問題の詳細を stderr に出力し、終了コード 2 で終了します。トレースバックは出力されません。

Claude Code

claude mcp add openproject \
  --env OPENPROJECT_URL=https://openproject.example.com \
  --env OPENPROJECT_API_KEY=your-api-key \
  -- uvx openproject-mcp-server

Claude Desktop およびその他の MCP クライアント

claude_desktop_config.json（またはクライアントに相当する mcpServers 設定）に追加します。

{
  "mcpServers": {
    "openproject": {
      "command": "uvx",
      "args": ["openproject-mcp-server"],
      "env": {
        "OPENPROJECT_URL": "https://openproject.example.com",
        "OPENPROJECT_API_KEY": "your-api-key"
      }
    }
  }
}

ソースから

git clone https://github.com/kar-thik/openproject-mcp
cd openproject-mcp
uv sync
uv run openproject-mcp-server

API トークンの更新またはローテーション

トークンが再生成、取り消し、または無効化された場合（OpenProject のメジャーアップグレードによって発生することがあります。すべてのツールが突然 authentication_failed / HTTP 401 で失敗するのが兆候です）、OpenProject の マイアカウント → アクセストークン で新しいトークンを生成し、キーを保存している場所で更新してください。

• シェル環境（最も簡単にローテーションできます）。 サーバーは OS の環境から OPENPROJECT_API_KEY を直接読み取るため、環境変数をグローバルに設定できます（例：~/.zshenv）。そのうえで、--env フラグを使わずにサーバーを登録します。

  claude mcp add openproject -- uvx openproject-mcp-server
  

  ローテーションするには、export の値を編集し、新しいターミナルを開いて再接続します。クライアント設定にシークレットが含まれることはありません。（シェルのプロファイルを読み込まない Claude Desktop などの GUI アプリでは、この方法は機能しません。）

• --env を使う Claude Code。 登録時にキーが保存されるため、置き換えてください。

  claude mcp remove openproject
  claude mcp add openproject \
    --env OPENPROJECT_URL=https://openproject.example.com \
    --env OPENPROJECT_API_KEY=new-key \
    -- uvx openproject-mcp-server
  

  /mcp で再接続してください（実行中のセッションは、再接続するまで古い環境を保持します）。

• Claude Desktop およびその他の JSON 設定を使うクライアント。 クライアント設定の OPENPROJECT_API_KEY の値を編集し、クライアントを再起動してください。

• .env ファイル。 ファイルを編集し、サーバーを再起動してください。

最近の OpenProject のバージョンでは複数の API トークンを並行して使用できるため、ダウンタイムなしでローテーションできます。新しいトークンを作成し、クライアントを切り替えてから、古いトークンを取り消してください。

設定

設定はすべて環境変数で行います。以下の表が正式なリファレンスです。サーバーが受け付けるのはこの26個の名前のみで、ほかの名前は受け付けません。READ_TIMEOUT や API_KEY のようなプレフィックスのない名前は意図的に無視されます（シェル内に余分な変数があっても、サーバーの設定を変更したり、動作を妨げたりすることはありません）。その他の未知の変数も同様に無視されます。サーバーの作業ディレクトリにある .env ファイルも同じ名前で読み込まれます。実際の環境変数が優先されます。ソースから利用する場合は、.env.example をひな形として使えます。

変数	デフォルト	用途
OPENPROJECT_URL	—（必須）	インスタンスのルート URL。例：https://openproject.example.com。末尾の /api/v3 は許容され、自動的に削除されます。
OPENPROJECT_API_KEY	—（必須*）	My account → Access tokens で取得した API キー。HTTP Basic の apikey:<token> として送信されます。
OPENPROJECT_OAUTH_TOKEN	未設定	API キーの代替となる OAuth ベアラートークン。*2 つの認証情報のうち、いずれか一方が必要です。
OPENPROJECT_MCP_ACCEPT_LANGUAGE	未設定	Accept-Language ヘッダーとして送信されます。OpenProject はこれに応じて検証メッセージをローカライズします。
OPENPROJECT_MCP_CA_BUNDLE	システムのトラストストア	プライベート CA の背後にあるインスタンス用の CA バンドル（PEM）へのパス。TLS の検証は常に行われます。無効にする方法は意図的に設けていません。
OPENPROJECT_MCP_READ_ONLY	false	読み取りツールのみを提供します。すべての書き込み、破壊的操作、管理者用ツールは起動時に削除されます。
OPENPROJECT_MCP_ADMIN_TOOLS	false	管理者に制限された 3 つのメンバーシップ書き込みツールを公開します（デフォルトでは非表示）。
OPENPROJECT_MCP_DISABLE	空	起動時にツールグループ全体を除外する、カンマ区切りのグループタグ（下記を参照）。
OPENPROJECT_MCP_PROFILE	core	core では起動時にモジュール対応グループが非表示になります。セッション中に enable_tool_group で再度有効にできます（下記を参照）。full ではすべてのグループが表示されます。
OPENPROJECT_MCP_INSECURE	false	認証トークンなしで --transport http を起動できるようにします。ローカル開発専用です。
OPENPROJECT_MCP_DOWNLOAD_DIR	./openproject-downloads	download_attachment がファイルを書き込むディレクトリ（存在しない場合は作成されます。デフォルトはサーバーの作業ディレクトリからの相対パスです）。
OPENPROJECT_MCP_UPLOAD_ROOT	未設定	設定すると、upload_attachment と create_work_package(attachment_paths) は、この既存ディレクトリ内のファイルのみを読み取ります。外部を指すパスやシンボリックリンクは拒否されます。--transport http での使用を推奨します。
OPENPROJECT_MCP_DOWNLOAD_ROOT	未設定	設定すると、download_attachment はこの既存ディレクトリ内にのみ書き込み、デフォルトでそこに保存します。範囲外の save_dir は拒否されます。--transport http での使用を推奨します。
OPENPROJECT_MCP_MAX_DOWNLOAD_MB	100	添付ファイルのダウンロードサイズ上限（MiB）。
OPENPROJECT_MCP_MAX_INLINE_MB	10	openproject://attachment リソースがインラインで返す添付ファイルのバイト数の上限（MiB）。ダウンロード上限を超えることはありません。
OPENPROJECT_MCP_CACHE_TTL	300	メタデータキャッシュ（ステータス、タイプ、優先度、スキーマ）の TTL（秒）。
OPENPROJECT_MCP_LOG_LEVEL	INFO	DEBUG、INFO、WARNING、ERROR、CRITICAL（大文字と小文字は区別されません）。
OPENPROJECT_MCP_LOG_FORMAT	text	text または json。ログは常に stderr に出力されます（stdout は stdio トランスポート用です）。
OPENPROJECT_MCP_LOG_BODIES	false	リクエスト／レスポンスの本文をログに記録します。DEBUG レベルの場合のみ有効で、認証情報はマスキングされます。開発用途専用です。
OPENPROJECT_MCP_OTEL	false	OpenTelemetry トレーシング用に予約されています。受け付けられますが、このリリースではまだ何にも接続されていません。設定してもトレースは出力されません。
OPENPROJECT_MCP_HTTP_HOST	127.0.0.1	--transport http のバインドアドレス。
OPENPROJECT_MCP_HTTP_PORT	8000	--transport http のポート。
OPENPROJECT_MCP_AUTH_TOKENS	未設定	--transport http が受け付けるベアラートークン（クライアントごとに 1 つなど）のカンマ区切りリスト。すべてのリクエストに、いずれかのトークンを含む Authorization: Bearer <token> が必要です。それ以外の場合は 401 が返されます。この設定がなく、OPENPROJECT_MCP_INSECURE=1 も設定されていない場合、HTTP トランスポートは起動を拒否します。トランスポートを参照してください。
OPENPROJECT_MCP_CONNECT_TIMEOUT	10	OpenProject への TCP/TLS 接続を待つ秒数。
OPENPROJECT_MCP_READ_TIMEOUT	30	レスポンスデータを待つ秒数。
OPENPROJECT_MCP_WRITE_TIMEOUT	60	リクエストデータの送信（アップロード）中に待つ秒数。
OPENPROJECT_MCP_POOL_TIMEOUT	5	プールから空き接続を取得するまで待つ秒数。
OPENPROJECT_MCP_MAX_CONNECTIONS	10	OpenProject への接続プールサイズ。
OPENPROJECT_MCP_MAX_RETRIES	3	冪等なリクエストの再試行回数。
シークレット（OPENPROJECT_API_KEY、OPENPROJECT_OAUTH_TOKEN、OPENPROJECT_MCP_AUTH_TOKENS）は Pydantic の SecretStr 値としてメモリ内に保持され、ログに書き込まれることはありません。すべてのログレコードで Authorization ヘッダーは伏せ字になります。

モデルが実行できる操作の制限

4 つの設定により、起動時にツールの範囲を絞り込めます。その後、次の例外を除き、プロセスが存続する間はツールリストが固定されます。enable_tool_group は core プロファイルで非表示になっているグループを、呼び出し元のセッションに限り再び有効にできます。

• OPENPROJECT_MCP_READ_ONLY=1 にすると、40 個の読み取りツールのみが提供されます。
• OPENPROJECT_MCP_ADMIN_TOOLS=1 にすると、メンバーシップを書き込む 3 つのツール（create_membership、update_membership、delete_membership）が表示されます。これらはデフォルトでは非表示です。
• OPENPROJECT_MCP_DISABLE を使うと、プロンプトのコストを抑えるためにグループ全体を除外できます。例：OPENPROJECT_MCP_DISABLE=meetings,news。有効なグループタグは、次のツールカタログの各セクションの先頭にあるタグと同じ、work_packages、wp_collaboration、attachments、git_activity、projects、queries、notifications、time_entries、versions、people、metadata、meetings、wiki、documents、budgets、news、reporting です。さらに、meetings のサブタグ meetings_recurring を指定すると、繰り返し会議に関する 6 つのツールのみが除外されます（meetings を指定した場合も、これらのツールは除外されます）。
• OPENPROJECT_MCP_PROFILE のデフォルトは core（0.4.0 以降）です。この設定では、モジュールに依存するグループ（meetings、news、documents、wiki、budgets、git_activity、reporting）と、2 つのレポート用プロンプトが非表示になり、セッション開始時のツールリストが小さくなります。最初からすべてのグループを表示するには、full に設定してください。モデルがいずれかのグループを必要とすると、enable_tool_group を呼び出して、呼び出し元のセッションに限りそのグループを再び有効にできます。その後、サーバーはそのセッションに tools/list_changed を送信するため、クライアントはこの通知に対応し、ツールリストを再読み込みする必要があります（お使いのクライアントが対応していない場合は、full に設定してください）。セッションのルールは、24 時間操作がないと期限切れになります。enable_tool_group で READ_ONLY、管理者向けの制限、OPENPROJECT_MCP_DISABLE を解除することはできません。また、このツールは metadata グループに属するため、そのグループを無効にすると利用できなくなります。

これら 4 つの設定とは別に、すべての破壊的操作ツール（恒久削除を行う 13 個のツール）は、実行前に明示的な confirm=true 引数を必要とします。

トランスポート

• stdio（デフォルト）— Claude Code、Claude Desktop、およびほとんどのローカル MCP クライアントで使用されます。 ログは stderr に出力され、stdout にはプロトコルのみが出力されます。

• Streamable HTTP — openproject-mcp-server --transport http。デフォルトでは 127.0.0.1:8000 にバインドします。--host／--port または OPENPROJECT_MCP_HTTP_HOST／ OPENPROJECT_MCP_HTTP_PORT で変更できます。HTTP トランスポートは、認証が設定されていない場合は起動しません。 カンマ区切りのベアラートークン一覧を OPENPROJECT_MCP_AUTH_TOKENS に設定するか、ローカル開発時に限り OPENPROJECT_MCP_INSECURE=1 を設定してください。

  トークンを設定した場合、MCP エンドポイントへのすべての HTTP リクエストに、 設定済みの値のいずれかと一致するトークンを含む Authorization: Bearer <token> ヘッダーが必要です （比較は定数時間で行われます）。トークンがない、形式が不正、または不明なリクエストは、 WWW-Authenticate ヘッダーを付けて 401 で拒否されます。複数のトークンをサポートしているため、 たとえばクライアントごとにトークンを発行し、それぞれを個別に無効化できます。トークンは ASCII である必要があり、 エンドポイントにはレート制限がないため、長いランダム値を使用してください。たとえば、 python -c "import secrets; print(secrets.token_urlsafe(32))" で生成できます。 OPENPROJECT_MCP_INSECURE=1 は、認証なしでエンドポイントを公開する開発専用の回避策です。

  サーバーは TLS を終端しないため、対策をしなければトークンはネットワーク上を平文で流れます。 デフォルトの 127.0.0.1 バインドを維持し、HTTP トランスポートを localhost の外部に公開する必要がある場合は、 TLS を終端するリバースプロキシ（nginx や Caddy など）の背後に配置してください。

  上流の ID は 1 つです。 ベアラートークンで決まるのはエンドポイントへのアクセス可否であり、 OpenProject でのユーザー ID ではありません。サーバーは単一の OPENPROJECT_API_KEY（または OAuth トークン）を保持し、 すべての HTTP クライアントはその OpenProject ユーザーとして操作し、メタデータキャッシュを共有します。 そのアカウントへのアクセスを許可できるクライアントに対してデプロイし、専用の最小権限の OpenProject ユーザーを発行してください。

  ファイルツールはサーバーのディスクにアクセスします。 upload_attachment、create_work_package (attachment_paths)、および download_attachment は、サーバーを実行しているマシン上のパスを読み書きします。 HTTP では、アクセス範囲を制限するまでこれらのツールは無効です。upload_attachment と attachment_paths には OPENPROJECT_MCP_UPLOAD_ROOT が、download_attachment には OPENPROJECT_MCP_DOWNLOAD_ROOT が必要です。 設定されるまではツールは非表示になり（attachment_paths は拒否されます）、サーバーは起動時の警告で不足している変数を示します。

ツール

91 個のツールがあります。読み取りが 42 個、書き込みが 46 個、管理者限定の書き込みが 3 個です。管理者向けツールは OPENPROJECT_MCP_ADMIN_TOOLS=1 を設定しない限り非表示です。また、破壊的な操作を行う 13 個のツールでは、呼び出しごとに confirm=true が必要です。各セクションの見出しには、OPENPROJECT_MCP_DISABLE で指定できるグループタグが記載されています。

作業パッケージ（work_packages）

ツール	種類	内容
search_work_packages	読み取り	ID が分からない場合に、テキストで作業パッケージを検索します。
list_work_packages	読み取り	構造化フィルターを使って作業パッケージを一覧表示します。主要な読み取りツールです。
get_work_package	読み取り	作業パッケージを詳細に読み取ります。説明、日付、カスタムフィールド、親、進捗が含まれます。
create_work_package	書き込み	OpenProject 独自のフォームエンドポイントで事前に検証したうえで、作業パッケージを作成します。
update_work_package	書き込み	楽観的ロックを使用して、作業パッケージの書き込み可能なフィールドを変更します。
bulk_update_work_packages	書き込み	アイテムごとの差分、検証結果、競合結果を確認しながら、最大 50 件の更新をプレビューまたは適用します。
delete_work_package	書き込み（破壊的）	作業パッケージと、それに付属するすべてのものを完全に削除します。

バッチワークフロー：プレビューするには、bulk_update_work_packages(updates=[{"id": 4821, "changes": {"target_versions": [3, 4]}}]) を呼び出します。返された変更を確認し、 その後 dry_run=false を指定して、各アイテムから返された lock_version を updates に含めて 再度実行します。事前チェックでエラーが発生すると、バッチ全体の書き込みが中止されます。後続の 競合によって一部のみ成功する場合があるため、すべてのアイテムを確認し、成功した更新を再実行しないでください。 unknown は、応答が失われる前に書き込みがコミットされた可能性があることを意味します。

コメント、関連付け、ウォッチャー、リマインダー（wp_collaboration）

ツール	種類	内容
list_work_package_comments	読み取り	作業パッケージのコメントスレッドと変更履歴を読み取ります。
add_work_package_comment	書き込み	作業パッケージにコメントを投稿します。
edit_work_package_comment	書き込み	既存の作業パッケージのコメントを書き換えます。
add_work_package_watcher	書き込み	ユーザーを作業パッケージの通知に登録します。
remove_work_package_watcher	書き込み	ユーザーを作業パッケージの通知から登録解除します。
create_work_package_relation	書き込み	2 つの作業パッケージを関連付けます（ブロック、後続、重複、関連など）。
update_work_package_relation	書き込み	既存の関連付けの種類、ラグ、説明を変更します。
delete_work_package_relation	書き込み（破壊的）	2 つの作業パッケージ間の関連付けを削除します。
toggle_comment_reaction	書き込み	絵文字で作業パッケージのコメントにリアクションするか、リアクションを取り消します。
set_work_package_reminder	書き込み	作業パッケージの個人的なリマインダーを設定、変更、解除します。
list_reminders	読み取り	今後予定されている自分の作業パッケージのリマインダーを一覧表示します。
execute_custom_action	書き込み	インスタンスで定義された作業パッケージ用のワンクリックアクションを実行します。

添付ファイルとファイルリンク（attachments）

ツール	種類	内容
list_attachments	読み取り	1 つのコンテナに添付されたファイルを一覧表示します。
download_attachment	読み取り	このサーバーを実行しているマシン上のファイルに、添付ファイルのバイトデータをダウンロードします。
upload_attachment	書き込み	ローカルファイルを作業パッケージ、Wiki ページ、会議、ドキュメント、予算、またはコメントに添付します。
delete_attachment	書き込み（破壊的）	OpenProject から添付ファイルを完全に削除します。
list_file_links	読み取り	作業パッケージにリンクされた外部ストレージ（Nextcloud、OneDrive/SharePoint）のファイルを一覧表示します。

Git とプルリクエスト（git_activity）

ツール	種類	内容
get_work_package_git_activity	読み取り	作業パッケージに関連するコードを表示します。コミット、プルリクエスト／マージリクエスト、CI ステータスが含まれます。
get_github_pull_request	読み取り	リンクされた GitHub のプルリクエストを 1 件、CI チェックの実行結果も含めて詳細に読み取ります。

プロジェクト（projects）

ツール	種類	機能
list_projects	読み取り	サーバー側でフィルタリングして、プロジェクトを1ページずつ一覧表示します。
get_project	読み取り	1つのプロジェクトの全情報を取得します。
create_project	書き込み	OpenProject 独自のフォームエンドポイントで事前に検証してから、プロジェクトを作成します。
update_project	書き込み	プロジェクトの名前、説明、公開範囲、親プロジェクト、ステータス、またはアーカイブ状態を変更します。
delete_project	書き込み（破壊的）	プロジェクトとその中にあるすべてのものを完全に削除するようスケジュールします。
copy_project	書き込み	プロジェクトの設定と、必要に応じてワークパッケージを新しいプロジェクトにコピーします。
get_job_status	読み取り	バックグラウンドジョブ（プロジェクトのコピー、スケジュール済みの削除）が完了したかどうかを確認します。
set_project_favorite	書き込み	認証済みユーザーのお気に入りにプロジェクトを追加、またはお気に入りから削除します（OpenProject 17+）。
list_project_phase_definitions	読み取り	インスタンス全体で使われるフェーズカタログ（Initiating、Planning、...）を、開始・完了のゲートとともに一覧表示します（OpenProject 16.1+）。
get_project_phase	読み取り	1つのプロジェクトのフェーズレコードを取得します。ID はワークパッケージの project_phase 参照から取得します。

保存済みクエリ（queries）

ツール	種類	機能
list_queries	読み取り	このユーザーが開ける、保存済みのワークパッケージビュー（クエリ）を一覧表示します。
run_query	読み取り	保存済みのビューを実行し、現時点のワークパッケージを取得します。
save_query	書き込み	フィルターセットを、チーム全員が開ける再利用可能な OpenProject ビューとして保存します。

通知（notifications）

ツール	種類	機能
list_notifications	読み取り	認証済みユーザーの OpenProject 受信箱を取得します。
mark_notifications	書き込み	1回の一括リクエストで、指定した通知を既読（または未読）にします。
mark_all_notifications_read	書き込み	フィルターに一致するすべての通知を既読にします。デフォルトでは受信箱全体が対象です。

時間管理（time_entries）

ツール	種類	機能
list_time_entries	読み取り	サーバー側でフィルタリングして記録済み時間を一覧表示し、必要に応じて正確な合計を取得します。
log_time	書き込み	ワークパッケージまたはプロジェクトに時間を記録します。
update_time_entry	書き込み	既存の時間記録を修正します。
delete_time_entry	書き込み（破壊的）	記録済みの時間を完全に削除します。

バージョンとスプリント（versions）

ツール	種類	機能
list_versions	読み取り	ワークパッケージに割り当て可能なバージョン（リリース、マイルストーン、スプリント）を一覧表示します。
list_sprints	読み取り	ワークパッケージの計画に使用できるスプリント（スクラムのタイムボックス）を一覧表示します。
get_sprint	読み取り	1つのスプリントの全情報（日時、ワークスペース、ライフサイクルステータス）を取得します。
create_version	書き込み	プロジェクト内にバージョン（リリース、マイルストーン、またはスプリント）を作成します。
update_version	書き込み	バージョンの名前、日付、説明、ステータス、または共有設定を変更します。
delete_version	書き込み（破壊的）	バージョンを完全に削除します。

ユーザーとメンバーシップ（people）

ツール	種類	機能
search_principals	読み取り	ユーザー、グループ、プレースホルダーユーザーを検索し、それらのIDを取得します。
get_user	読み取り	1人のユーザーのプロフィール（名前、ログイン名、メールアドレス、管理者フラグ、ステータス）を取得します。
list_memberships	読み取り	誰がどのプロジェクトに、どのロールでアクセスできるかを一覧表示します。
create_membership	管理者書き込み	プリンシパルにプロジェクト内の1つ以上のロールを付与します。
update_membership	管理者書き込み	既存のメンバーシップのロールを置き換えます。
delete_membership	管理者書き込み（破壊的）	プリンシパルのプロジェクトへのアクセス権を取り消します。
list_roles	読み取り	このインスタンスで定義されているロールをIDとともに一覧表示します。

メンバーシップを書き込む3つのツールを使用するには、OPENPROJECT_MCP_ADMIN_TOOLS=1（およびメンバーの管理権限を持つ OpenProject アカウント）が必要です。

インスタンスのメタデータとスキーマ（metadata）

ツール	種別	説明
get_instance_info	読み取り	OpenProject への接続を確認し、このインスタンスでサポートされている内容を報告します。
get_project_metadata	読み取り	このインスタンスで実際に有効な ID と名前（タイプ、ステータス、優先度など）を一覧表示します。
get_work_package_schema	読み取り	このプロジェクトで、このタイプの作業パッケージが受け付けるフィールドを表示します。
list_permissions	読み取り	認証済みユーザーに許可されている操作を、全体または特定のプロジェクトについて一覧表示します。
enable_tool_group	読み取り	OPENPROJECT_MCP_PROFILE=core によって非表示になったツールグループを、このセッションで再び有効にします。OpenProject への呼び出しは行いません。

会議（meetings）

定期会議用の6つのツールには meetings_recurring タグも付いているため、OPENPROJECT_MCP_DISABLE=meetings_recurring を指定すると、それらのツールだけが無効になります（利用には OpenProject 17.4 以降が必要です）。

ツール	種別	説明
list_meetings	読み取り	会議を一覧表示します。今後の会議や、すでに開催された会議を確認できます。
get_meeting	読み取り	1件の会議の全容を読み取ります。参加者、議題、記録された成果を確認できます。
create_meeting	書き込み	プロジェクトで会議を予定し、必要に応じて参加者を招待します。
update_meeting	書き込み	会議のタイトル、日時、場所、招待者リストを変更するか、ライフサイクルの状態を変更します。
delete_meeting	書き込み（破壊的操作）	会議を議題や記録された成果とともに完全に削除します。
add_meeting_agenda_item	書き込み	会議の議題に項目を1つ追加します。必要に応じて作業パッケージに関連付けられます。
update_meeting_agenda_item	書き込み	議題項目を編集します。タイトルやメモの変更、日時の変更、並べ替え、リンクの付け替えができます。
delete_meeting_agenda_item	書き込み（破壊的操作）	議題項目を、その項目に記録された成果とともに完全に削除します。
add_meeting_outcome	書き込み	議題項目に対する成果（決定、メモ、フォローアップチケットなど）を記録します。
update_meeting_outcome	書き込み	記録された成果の種類、テキスト、リンクされた作業パッケージを修正します。
delete_meeting_outcome	書き込み（破壊的操作）	開催中の会議の議事録から、記録された成果を完全に削除します。
list_recurring_meetings	読み取り	定期会議シリーズを一覧表示します。個々の会議ではなく、繰り返しルールを確認できます。
get_recurring_meeting	読み取り	1つの定期会議シリーズの全容を読み取ります。スケジュールと次回の開催予定を確認できます。
create_recurring_meeting	書き込み	定期会議シリーズを作成します。スケジュールと、各開催回で複製されるテンプレートを設定します。
delete_recurring_meeting	書き込み（破壊的操作）	テンプレート、スケジュール、すべての開催回を含む定期会議シリーズを完全に削除します。
init_recurring_meeting_occurrence	書き込み	シリーズの開催回を、テンプレートから複製した実際の会議として作成します。
cancel_recurring_meeting_occurrence	書き込み（破壊的操作）	スケジュールに手を加えず、シリーズの開催回を1つキャンセルして、その回をスキップします。

Wiki（wiki）

ツール	種別	説明
get_wiki_page	読み取り	Wiki ページの識別情報とプロジェクトを読み取ります。ページの内容は対象外です（API v3 ではページ本文が公開されていません）。

ドキュメント（documents）

ツール	種別	説明
list_documents	読み取り	すべてのプロジェクトを対象に、自分が閲覧できるドキュメントを一覧表示します。
get_document	読み取り	1件のドキュメントを、説明文全体とともに読み取ります。

予算（budgets）

ツール	種別	説明
list_budgets	読み取り	プロジェクトの予算を一覧表示します。ID と名前を確認できます（API v3 で公開されているのはこれだけです）。

ニュース（news）

ツール	種類	内容
list_news	読み取り	プロジェクトのニュースを一覧表示します。チームがプロジェクトの概要で公開するお知らせです。
get_news	読み取り	Markdown 本文を含むニュース項目を全文表示します。
create_news	書き込み	プロジェクトでニュースのお知らせを公開します。
update_news	書き込み	公開済みのニュース項目を修正または書き直します。
delete_news	書き込み（破壊的）	ニュース項目を完全に削除します。

レポート（reporting）

ツール	種類	内容
get_project_report_data	読み取り	1 つのプロジェクトと日付範囲について、ステータスレポートを集計します。正確な件数、詳細を確認するための呼び出しに使えるサンプル行、各セクションの状態を返します。

プロンプトとリソース

レポートデータでは、指定した期間内に更新された、現在クローズ済みの作業を closed_updated で示します。これは v0.3.0 で従来の closed フィールドに置き換わるものです。作業がいつ完了したかは示しません。裏付けとなるデータがない場合、スプリントの健全性は評価されません。

4 つのプロンプトテンプレートが、最新の OpenProject データを実用的なブリーフィングに変換します。

• weekly_report — 1 つのプロジェクトの週次ステータスレポートです。現在クローズ済みかつ更新済みの作業、進行中の作業、計画済みの作業、時間数、障害要因を示します。
• daily_standup — 1 つのプロジェクトの本日のスタンドアップです。昨日の進捗、本日期限の作業、ブロックされている作業を示します。
• triage_inbox — 未読の通知を理由別にまとめ、対応を提案します。
• groom_backlog — プロジェクトの未完了バックログを確認し、担当者未設定、長期間更新されていない作業、見積もりのない作業を探します。

3 つのリソーステンプレートは、安定した URI で OpenProject オブジェクトを公開します。

• openproject://work_package/{id} — 1 つのワークパッケージを JSON 形式で表示します。
• openproject://project/{identifier} — 1 つのプロジェクトを JSON 形式で表示します（識別子のスラッグまたは数値の id）。
• openproject://attachment/{id} — 検出された MIME タイプとともに、添付ファイルのバイト列を返します。上限は OPENPROJECT_MCP_MAX_INLINE_MB です。

対応する OpenProject バージョン

このサーバーは OpenProject 14 LTS から 17.x を対象としています。単一の API 仕様を前提とするのではなく、必要になった時点でインスタンスを遅延プローブし、結果を 1 時間キャッシュします。バージョンに依存する項目は次のとおりです。

• 対象バージョン：対応するすべてのインスタンスで、ワークパッケージの詳細に target_versions が表示されます。作成／更新ではバージョン ID のリストを受け付けます（[] でクリア）。スキーマは 17.8 以降では targetVersions、それより前では従来の単一の version を選択します。従来の version 引数は引き続き単一値のエイリアスとして使えますが、両方を指定しないでください。複数のバージョンが割り当てられている場合、読み取り時の値は null です。
• 内部（非公開）コメントには OpenProject >= 16 が必要です。古いサーバーは内部フラグを警告なしに無視します。そのため 16 未満では、内部に保つよう指定したコメントが公開されてしまうのを避けるため、サーバーは明確なエラーを返します。
• 絵文字リアクション（toggle_comment_reaction）には OpenProject >= 16 が必要です。バージョンから対応状況を判定し、呼び出し時の 404 も許容します。
• プロジェクトのお気に入り登録（set_project_favorite）には OpenProject >= 17 が必要です。同様に、404 を許容します。
• 時間エントリーのフィルター：ワークパッケージのフィルターをプローブします（entityId を使用し、利用できない場合は 15.x より前の表記である workPackage にフォールバックします）。
• 権限コンテキスト（list_permissions）：コンテキストのプレフィックスをプローブします（p{id} を使用し、17.2 で導入された w{id} の表記にフォールバックします）。
• 会議の時間フィルター：OpenProject 17.6 でワイヤー仕様が変更されました。list_meetings はインスタンスが受け付ける表記を検出し、キャッシュします。
• ストーリーポイントには Backlogs モジュールと、Backlogs がストーリーとして扱うタイプが必要です。17.x では、それ以外の場合 story_points は拒否されます。14.x では書き込みを受け付けますが、値は警告なしに破棄されるため、結果に保存されなかったことを示す注記が含まれます（一括プレビューでは書き込み前に警告します）。

オプションのインスタンスモジュールに依存する機能（会議、ニュース、ドキュメント、予算、Wiki、バックログ、GitHub／GitLab 連携、外部ストレージ）は、モジュールがない場合も実際の状況に即して動作します。一覧表示ツールは、該当するモジュールがないことを示す注記を結果内に含めて空のページを返し、詳細表示ツールは、404 の 2 通りの解釈を説明する構造化エラーを返します。

セキュリティ

• API キーと OAuth トークンは SecretStr として保持され、ログに記録されることはありません。すべてのログレコードで、Authorization ヘッダーと Cookie ヘッダーはマスキングされます。リクエスト／レスポンス本文は、開発時に OPENPROJECT_MCP_LOG_BODIES=1 を設定した場合に限り、DEBUG レベルでログに記録されます。
• リダイレクト先が OpenProject のオリジンから外れる場合、Authorization ヘッダーは必ず削除されます。添付ファイルのダウンロードは、署名付きオブジェクトストレージ URL にリダイレクトされるため、認証情報を転送してはいけません。
• TLS は常に検証されます。OPENPROJECT_MCP_CA_BUNDLE を使ってプライベート CA をサポートできます。TLS 検証を無効にするスイッチは意図的に用意していません。
• 添付ファイルのダウンロードでは、OpenProject のウイルススキャナーの結果が尊重されます。隔離されたファイルは決して取得されず、構造化された attachment_quarantined エラーが返されます。ダウンロードサイズは OPENPROJECT_MCP_MAX_DOWNLOAD_MB で制限され、サニタイズされたファイル名で保存されます（ディレクトリ区切り文字とパストラバーサルのシーケンスは無効化されます）。また、ファイルの SHA-256 が報告されます。
• 破壊的なツールには confirm=true が必要であり、クライアントが事前にユーザーへ確認できるよう注釈が付けられています。
• HTTP トランスポートは、OPENPROJECT_MCP_AUTH_TOKENS が設定されていない場合、起動を拒否します。また、すべてのリクエストで Authorization: Bearer ヘッダーを検証します。トークンがない場合や無効な場合は 401 で拒否され、トークンの比較には一定時間の比較が用いられます。サーバーは TLS を終端しません。デフォルトの 127.0.0.1 バインドを維持し、他の場所からポートにアクセスできるようにする必要がある場合は、手前に TLS を終端するリバースプロキシを配置してください（トランスポートを参照）。すべての HTTP クライアントは、サーバーと同じ OpenProject ID を共有します。ファイルツールは OPENPROJECT_MCP_UPLOAD_ROOT／OPENPROJECT_MCP_DOWNLOAD_ROOT で制限してください。
• ダウンロードファイルは排他的に作成されます（同じ名前のファイルが同時にダウンロードされる場合でも、既存ファイルは上書きされません）。転送に失敗した場合やキャンセルされた場合は、その転送で作成したファイルだけが削除されます。

トラブルシューティング

症状	意味と対処方法
「cannot start, configuration is incomplete」と表示され、サーバーが終了する	openproject-mcp-server --check を実行し、表示された問題を修正してください。変数の一覧は上記の設定セクションを参照してください。
401 authentication_failed	API キーが間違っている、失効している、またはブロックされたアカウントのものです。マイアカウント → アクセストークンから新しいトークンを生成してください。
403 permission_denied	アカウントは認証されていますが、そのプロジェクトでのロール権限が不足しているか、該当するモジュールが無効になっています。
モジュールがないという注記とともに空のリストが返される	該当する OpenProject モジュール（会議、ニュース、ドキュメントなど）がインストールされていないか、プロジェクトで有効になっていません。空の結果は正しい応答であり、エラーではありません。
TLS 証明書エラー	インスタンスがプライベート CA を使用しています。OPENPROJECT_MCP_CA_BUNDLE にその PEM バンドルを指定してください。検証を無効にするオプションはありません。
--transport http の起動が拒否される	OPENPROJECT_MCP_AUTH_TOKENS（カンマ区切りのベアラートークン）を設定してください。または、ローカル開発に限り OPENPROJECT_MCP_INSECURE=1 を設定してください。詳しくはトランスポートを参照してください。
MCP HTTP エンドポイント自体から 401 が返される	リクエストの Authorization: Bearer <token> ヘッダーがないか、設定済みの OPENPROJECT_MCP_AUTH_TOKENS のいずれの値とも一致していません。クライアントのトークンに誤記がないか確認してください。これは上記の上流からの 401 authentication_failed とは異なり、OpenProject API キーに関するエラーです。
プロキシ	基盤となる HTTP クライアントは、標準の HTTPS_PROXY／ALL_PROXY／NO_PROXY 環境変数に対応しています。

問題を報告する際は、OpenProject のバージョン、openproject-mcp-server --version の出力、および openproject-mcp-server --check の出力を添えてください。

開発

git clone https://github.com/kar-thik/openproject-mcp
cd openproject-mcp
uv sync --group dev
uv run pytest              # entire suite runs offline (respx-mocked HTTP), no instance needed
uv run ruff check .
uv run ruff format --check .
uv run pyright             # strict mode

デフォルトのテストスイートはオフラインのままです。オプトインの互換性チェックは、Compatibility ワークフローで最新の公式 OpenProject 14.6、15.5、16.6、17.8 のコンテナに対して実行されます（17.8 では単一バージョンモードと複数バージョンモードの両方を含みます）。Docker を起動した状態でローカル実行するには、次のようにします。

uv run python scripts/live_smoke.py --image openproject/openproject:17.8.0

テストハーネスは、非公開プロジェクト、一時ユーザー、カスタムフィールド、バージョンを用意し、MCP 経由でテストした後、コンテナとそのボリュームを削除します。既存のインスタンスや認証情報は使用されません。--live-openproject を使い、使い捨てのフィクスチャファイルを指定しない限り、pytest を直接実行した場合はこれらのテストはスキップされます。 技術仕様の全文は SPEC.md にあります。

リリース手順は CONTRIBUTING.md に記載されています。

ライセンスと商標

MIT — LICENSE を参照してください。

これはコミュニティプロジェクトです。OpenProject GmbH と提携しておらず、同社による承認やサポートも受けていません。「OpenProject」は OpenProject GmbH の商標であり、ここでは相互運用性を示す目的でのみ使用しています。