oec.sh

oec.sh MCP サーバー

AI アシスタント（Claude Code、Claude Desktop、Cursor などの MCP クライアント）から、oec.sh の組織を操作できます。サーバー、プロジェクト、環境の確認、環境の Odoo ログやリアルタイムのメトリクスの閲覧、デプロイ、再起動、モジュールの更新、バックアップの作成、タスクの完了までの追跡が可能です。

このサーバー独自の権限が追加されることはありません。すべてのツールは、oec.sh Public API を お客様の API キーで呼び出すものです。そのため、キーの種類（読み取り専用か、フルアクセスか）、スコープ（組織全体か、1 つのプロジェクトか）、プラン、クォータ、監査ログは、ほかの API クライアントとまったく同じように適用されます。

要件： Starter プラン以上の oec.sh 組織、およびダッシュボードの Settings > API Keys で発行した API キー。ローカルモードでは Node.js 22 以降が必要です。

キーを選択する

キー	プレフィックス	アシスタントが実行できる操作
読み取り専用（まずはこちらを推奨）	oec_live_ro_	読み取りツールのみ
フルアクセス	oec_live_rw_	読み取りツールと書き込みツール（デプロイ、再起動、作成など）

プロジェクトスコープのキーを使うと、アシスタントの操作対象を 1 つのプロジェクトに限定できます。アシスタントが 1 つのプロジェクトだけを操作する場合は、必ずこのキーを使ってください。

サーバーはプレフィックスからキーの種類を判別し、そのキーで使用できるツールのみを提供します。

インストール：ローカルモード（stdio）

MCP クライアントが、お使いのコンピューター上でサーバーを起動します。キーはお使いのコンピューター内に保管され、api.oec.sh にのみ送信されます。

Claude Code

claude mcp add oecsh -e OECSH_API_KEY=oec_live_ro_your_key -- npx -y @oecsh/mcp-server

Claude Desktop

claude_desktop_config.json（Settings > Developer > Edit Config）に追加し、Claude Desktop を再起動します。

{
  "mcpServers": {
    "oecsh": {
      "command": "npx",
      "args": ["-y", "@oecsh/mcp-server"],
      "env": { "OECSH_API_KEY": "oec_live_ro_your_key" }
    }
  }
}

Cursor

~/.cursor/mcp.json（すべてのプロジェクト）または .cursor/mcp.json（1 つのプロジェクト）に追加します。

{
  "mcpServers": {
    "oecsh": {
      "command": "npx",
      "args": ["-y", "@oecsh/mcp-server"],
      "env": { "OECSH_API_KEY": "oec_live_ro_your_key" }
    }
  }
}

キーを含むファイルをコミットしないでください。

設定（ローカルモード）

変数	意味
OECSH_API_KEY	API キー。必須です。
OECSH_ALLOW	オプトインするツールをカンマ区切りで指定します：destructive、backup-download。デフォルトは空です。
OECSH_API_URL	API アドレス。デフォルトは https://api.oec.sh/api/public/v1 です。oec.sh サポートから依頼された場合のみ変更してください。

ホステッドモード（ストリーミング可能な HTTP）

https://mcp.oec.sh/mcp。インストールは不要です。クライアントはリクエストごとに Authorization ヘッダーで API キーを送信します。サーバーはそのリクエストに限ってキーを API に転送し、情報を保存しません。

Claude Code：

claude mcp add --transport http oecsh https://mcp.oec.sh/mcp \
  --header "Authorization: Bearer oec_live_ro_your_key"

Cursor（mcp.json）：

{
  "mcpServers": {
    "oecsh": {
      "url": "https://mcp.oec.sh/mcp",
      "headers": { "Authorization": "Bearer oec_live_ro_your_key" }
    }
  }
}

ホステッドモードでオプトインツールを有効にするには、ヘッダー X-OECSH-Allow: destructive（または backup-download、あるいは両方をカンマ区切り）を追加します。

claude.ai のウェブコネクターなど、OAuth 経由でのみ接続するクライアントは、まだホステッドサーバーを利用できません。

mcp.oec.sh のホステッドサーバーは、お客様のアドレスを API に渡します（後述の OECSH_MCP_PROXY_SECRET を設定しているため）。そのため、繰り返し拒否されたキーをブロックする API の制限は、共有サーバーのアドレスではなく、お客様のアドレスを基準に適用されます。どちらの方式でも、レート制限は API キーごとに適用されます。

ツール

すべてのツール名は oecsh_ で始まります。リスト取得ツールは limit（1～100、デフォルトは 20）と cursor（前ページの next_cursor）を受け取り、items、count、total、has_more、next_cursor を返します。

読み取りツール（任意のキー）

ツール	機能
oecsh_get_organization	プラン、上限、現在の使用状況
oecsh_list_servers, oecsh_get_server	サーバー、サイズ、準備状況
oecsh_get_server_metrics	自身が所有するサーバー（共有サーバーを除く）のライブ CPU、メモリ、ディスク、ネットワーク
oecsh_list_projects, oecsh_get_project	プロジェクト
oecsh_list_environments	プロジェクトの環境。ステータスで絞り込むこともできます
oecsh_get_environment	ヘルス状態と直近のデプロイを含む、1 つの環境
oecsh_get_runtime_logs	環境の Odoo または PostgreSQL ログの最新行（最大 1000 行）。サーバーからライブで読み取ります
oecsh_get_environment_metrics	環境コンテナのライブ CPU とメモリ、およびディスクサイズ
oecsh_list_deployments	環境のデプロイ履歴
oecsh_get_task	任意のタスクのステータスと進捗
oecsh_wait_for_task	タスクが完了するまで待機します
oecsh_get_task_log	タスクのステップログとエラー
oecsh_list_backups, oecsh_get_backup	環境のバックアップ一覧。1 つのバックアップ
oecsh_list_webhooks, oecsh_get_webhook, oecsh_list_webhook_deliveries	送信 Webhook と最近の配信
oecsh_list_changelog	oec.sh のリリースノート（新しいものから順）。バージョン（since_version）または日付（since_date）以降に限定することもできます
oecsh_list_support_tickets, oecsh_get_support_ticket	組織のサポートチケット一覧。公開返信（内部メモは含みません）を含む 1 件のチケット。Support tickets を有効にした組織スコープのキーが必要です（Settings > API Keys）

書き込みツール（フルアクセスキー。データを削除するものはありません）

ツール	機能
oecsh_deploy_environment	ブランチを取得して再デプロイします。モジュールの更新もできます
oecsh_restart_environment, oecsh_start_environment, oecsh_stop_environment	再起動、起動、停止
oecsh_quick_update_environment	取得して再起動し、すべてのモジュールまたは一部のモジュールを更新します
oecsh_create_backup	手動バックアップを開始します
oecsh_create_project, oecsh_update_project	プロジェクト（作成には組織スコープのキーが必要です）。プロジェクトのリポジトリまたは Git プロバイダーの変更は、オプトインのツールです
oecsh_create_environment, oecsh_update_environment	環境

oecsh_create_webhook と oecsh_rotate_webhook_secret は、API では一度しか表示されないため、Webhook の署名シークレットを返します。シークレットは会話の記録に残り、ツールの結果にもその旨が示されます。記録が共有されている場合や、他の人が読める場所に保存されている場合は、ダッシュボード（Settings > Webhooks）でシークレットをローテーションし、新しいシークレットは受信側にご自身で渡してください。アシスタントを通じてローテーションすると、新しいシークレットも記録に残ります。

作業を開始する書き込みツールは task_id を返します。アシスタントは続けて oecsh_wait_for_task を呼び出します。デプロイ、再起動、停止、クイック更新、2 つの更新ツールには破壊的操作のマークが付いています（実行中のコードを置き換える、サイトを停止する、または設定を上書きするため）。この注意書きに従うクライアントは、実行前に確認を求めます。作成ツールと起動ツールにはマークが付いていません。

オプトインツール

有効にするまではオフです。各ツールには破壊的な操作のマークが付いていますが、これはあくまで目安です。ほとんどのクライアントでは、ツールを自動承認していない限り、実行前に承認を求められます。これらのツールをクライアントの自動承認リストや許可リストに追加しないでください。

また、これらのツールは confirm 引数（復元の場合は confirm_environment_name）を受け取ります。この引数にはリソース名を正確に入力する必要があり、サーバーは実際のリソース名と照合してから処理を実行します。Webhook の削除やシークレットのローテーションでは、名前として Webhook の URL を指定します。Webhook の作成、テスト、URL の変更では、データの送信先となるホストを指定します（https://hooks.example.com/oec の場合は hooks.example.com と入力します）。サーバーは URL からホストを読み取るため、https://[email protected]/ の場合は other.example です。Webhook のほかの設定を変更する場合、confirm は必要ありません。アシスタントには名前を尋ねるよう指示されていますが、リストツールを使って名前を取得することもできるため、引数だけでは、あなたが名前を入力したことを証明できません。そのため、クライアントが MCP エリシテーション（サーバーからフォームを表示できる機能）に対応している場合、サーバーはクライアント独自のプロンプトであなたにも名前の入力を求めます。このプロンプトには操作とリソースが表示され、承認され、入力した名前が一致した場合にのみ処理が進みます。拒否したり、別の名前を入力したりした場合は、何も変更されません。エリシテーションに対応していないクライアントと、セッションを保持しないため要求できないホステッドサーバーでは、confirm 引数のみで確認します。

オプトイン	ツール	キー
destructive	oecsh_delete_environment、oecsh_delete_project、oecsh_delete_webhook、oecsh_rotate_webhook_secret、oecsh_revoke_api_key、oecsh_reinitialize_modules、oecsh_restore_backup、oecsh_update_project_repository、oecsh_create_webhook、oecsh_update_webhook、oecsh_test_webhook	フルアクセス（キーの失効とプロジェクトの削除は組織のスコープ）
backup-download	oecsh_get_backup_download_links（データベース全体のダンプへのリンク。デフォルトで5分間有効、最長60分間）	すべて

Webhook の作成、変更、テストはオプトインです。Webhook は oec.sh のデータを指定された任意の HTTPS URL に送信し、テストではその場でデータが送信されるためです。たとえば Odoo のログ行など、他の人が結果に書き込んだテキストによって、アシスタントが Webhook の送信先をその人のアドレスにするよう指示される可能性があります。プロジェクトのリポジトリや Git プロバイダーの変更（oecsh_update_project_repository）も同じ理由でオプトインです。以降のデプロイでは、新しいリポジトリのコードがサーバー上で実行され、組織の Git トークンをどのホストに送るかは Git プロバイダーによって決まります。oecsh_update_project は、プロジェクトに関するそれ以外のすべてを変更します。ブランチ名（branch、default_branch）には実在するブランチ名を指定する必要があります。refs/...、pull/...、merge-requests/... などの参照パス、コミット ID のみの指定、- で始まる名前は拒否されるため、フォークのプルリクエストのコードがデプロイされることはありません。

oecsh_get_backup_download_links は警告を返します。リンクを持っている人は、有効期限が切れるまでデータベース全体をダウンロードできます。また、リンクは会話の記録にも残ります。

読み取り専用キーでは、サーバーが提供するツールは19個です（backup-download を有効にすると20個）。フルアクセスキーでは29個、destructive を有効にすると40個、両方のオプトインを有効にすると41個です。

oecsh_restore_backup は、ある環境のデータベースとファイルを、同じ環境の完了済みバックアップで上書きします（先に現在のデータの安全用バックアップを作成します）。その後、追跡用のタスクを返します。復元またはダウンロードリンクの取得で入力する名前は、環境の現在の名前です。API の一覧に表示されない停止中または破損した環境の場合は、バックアップに記録されている名前を入力します（oecsh_get_backup を参照してください）。別の環境への復元はダッシュボードから行ってください。

サーバー登録トークンは、このサーバーからは利用できません。

制限

• API リクエストはすべて、キーのレート制限にカウントされます。読み取りは毎分 120 回、書き込みは毎分 20 回で、それぞれ別にカウントされます。
• ほとんどのツールは API リクエストを 1 回または 2 回行います。oecsh_get_backup_download_links と oecsh_restore_backup は 3 回、その他の確認済みの破壊的操作ツールは 2 回（名前を確認するために、先にリソースを読み取ります）行います。ただし、Webhook の作成または URL の変更では、指定された URL のホストを確認するため、1 回だけ行います。
• oecsh_get_runtime_logs、oecsh_get_environment_metrics、oecsh_get_server_metrics は呼び出しのたびにサーバーにアクセスするため、API では環境またはサーバーごとに、それぞれ毎分 6 回までに制限されています。
• oecsh_wait_for_task は最初の 30 秒間は 5 秒ごと、その後は 10 秒ごとにタスクをポーリングします。また、API がキーに対して報告する読み取り制限の 5 分の 1 を超えて消費することはありません（毎分 20 回の制限の場合、15 秒ごとに 1 回ポーリングします）。多くのクライアントはツール呼び出しを 60 秒後に諦めるため、各呼び出しの待機時間は最大 50 秒、ホストモードでは最大 45 秒です。タスクの実行中は、アシスタントがこのツールを再度呼び出します。ローカルモードでは、クライアントが進捗メモを要求した場合（各ポーリングの後にメモを送信します）、またはアシスタントがより長い timeout_seconds を渡した場合、最大 10 分間待機します。
• 制限に達すると、ツールは API の Retry-After（これがない場合は次の 1 分の区切りまで）に基づいて、待機時間を通知します。待機時間が 10 秒以下の場合は、それ自体を 1 回再試行します。また、oecsh_wait_for_task は自身の制限時間内に収まる待機時間を待ちます。
• デプロイ、再起動、復元などのアクションに対する応答がネットワーク上で失われた場合、サーバーは同じ冪等性キーを使ってもう一度リクエストするため、API はアクションを二重に開始せず、最初の応答を返します。
• oecsh_get_task_log はタスク自身のログを最大 1000 行返します。oecsh_get_runtime_logs は Odoo または PostgreSQL のログを返します。どちらも最新の 60,000 文字で切り詰められ（truncated が設定されます）、各応答がクライアントの受け入れ可能な範囲に収まるようになっています。
• 実行中、停止中、一時停止中、エラー状態の環境はすべて表示されます。削除済みの環境には「見つかりません」と応答しますが、そのバックアップとタスクは引き続き読み取れます。
• 各 API リクエストは 30 秒後にタイムアウトします。ホスト型サーバーが受け付けるリクエスト本文の上限は 1 MB です。

セキュリティに関する注意事項

• キーは呼び出し前に正しい形式かどうか確認され、設定済みの API に対する Authorization ヘッダーでのみ送信されます。また、すべての出力、エラー、ログ行から削除されます。サーバーがキーを出力することはありません。
• API アドレスには https を使用する必要があります（例外として、localhost への plain http は使用できます）。また、サーバーはリダイレクトを追跡しないため、キーが平文で送信されたり、別のアドレスに再送されたりすることはありません。
• ホストモードでは、API アドレスはサーバーによって固定されます。クライアントがキーの送信先として別のホストを指定することはできません。形式が正しくないキーを含むリクエストは、本文を読み取る前に拒否されます。また、API が直前に拒否したキーは、5 分間ローカルで拒否されます。API は拒否したキーが 10 件に達すると、アドレスを 15 分間ブロックします。そのため、サーバーがまだ使用できることを確認していないキーを使ったツール呼び出しは、API の拒否数がリセットされるまで最大 6 回で止まります。最近使用できたキーは制限されません。サーバーが API に呼び出し元のアドレスを渡す場合（OECSH_MCP_PROXY_SECRET）、拒否数は呼び出し元アドレスごとに記録されます。渡さない場合は、API からすべてのホストユーザーがサーバーの 1 つのアドレスとして見えるため、サーバー全体で 1 つの拒否数が記録されます。メモリにはキーのハッシュのみが保存されます。各リクエストには JSON-RPC メッセージが 1 つ含まれます（バッチは拒否されます）。
• アシスタントが渡すすべての ID は、リクエストに含める前に UUID であることが確認されます。
• アシスタントが開始するバックアップは、組織独自のストレージにのみ保存されます。API は、別の組織に属するストレージ場所を拒否します。
• 結果に含まれる名前、メモ、ブランチ名、ログテキストはお客様のデータです。データとして返され、サーバーはそれらに含まれる指示に従わないようアシスタントに伝えます。他の人が書いたテキスト（ランタイムログやタスクログ、タスクのエラーメッセージ、デプロイ履歴、バックアップのメモやスナップショット）を含む結果には、そのテキストの前に、その旨を示す notice フィールドが付きます。また、これらのツールはオープンワールドとしてマークされています。Webhook の配信一覧には、受信先 URL が返した本文は含まれません。その URL の運用者が本文を記述するためです。
• ホストモードでは、キーごとに最大 3 件、呼び出し元アドレスごとに最大 10 件のツール呼び出しが同時に実行されます。それを超えると、「too many tool calls」エラーが返されます。エラーメッセージでは、サーバーが使用するアドレスの代わりに「the oec.sh API」と表示されます。また、API 独自の JSON ではない応答は省かれます。
• API キーをチャットに貼り付けないでください。アシスタントにキーを渡す必要はありません。サーバーは設定からキーを読み取り、チャットに入力した内容はすべてトランスクリプトに残ります。
• MCP クライアントの設定ファイル（claude_desktop_config.json、~/.claude.json、mcp.json など）には、キーが平文で保存されます。これらをバージョン管理、共有するバックアップ、画面共有に含めないでください。
• Claude Code では、サーバーを --scope project で追加しないでください。プロジェクトに .mcp.json が書き込まれますが、このファイルはコミットすることを想定しています。デフォルト（local）または --scope user を使用してください。
• 破壊的なツールや機密性の高いツールは、デフォルトで無効になっています。読み取り専用でプロジェクトにスコープを限定したキーを優先し、アシスタントが変更を加える必要がある場合にのみ、フルアクセスキーを与えてください。
• キーが漏えいした場合は、すぐに失効させてください：Settings > API Keys。

HTTP サーバーを自分で実行する

docker build -t oecsh-mcp ./mcp-server
docker run -p 127.0.0.1:8080:8080 -e OECSH_MCP_ALLOWED_HOSTS=localhost oecsh-mcp

オリジンには、プロキシ経由でのみ到達できるようにしてください（mcp.oec.sh の場合は、Cloudflare、次に Traefik）。ポートはループバックに公開するか、プロキシの Docker ネットワークのみに公開し、パブリックインターフェースには決して公開しないでください。サーバーが API に渡す呼び出し元のアドレスと、アドレスごとの制限は、手前のプロキシを前提としています。

本番環境では、OECSH_MCP_ALLOWED_HOSTS にパブリックホスト名（例：mcp.oec.sh）を設定してください。ループバック以外にバインドする場合、OECSH_MCP_ALLOW_ANY_HOST=1 が設定されていない限り、この設定がないとサーバーは起動を拒否します。

変数	デフォルト	意味
OECSH_MCP_HOST	127.0.0.1（イメージ内では 0.0.0.0）	バインドアドレス
OECSH_MCP_PORT	8080	ポート
OECSH_API_URL	https://api.oec.sh/api/public/v1	キーの送信先 API。localhost を除き、https を使用する必要があります
OECSH_API_ALLOW_HTTP	（オフ）	1 を設定すると、同じ内部ネットワーク上の API に限り、ループバック以外の OECSH_API_URL への平文 http を許可します
OECSH_MCP_MAX_BODY_BYTES	1048576	リクエスト本文の最大サイズ
OECSH_MCP_ALLOWED_HOSTS	（なし）	許可するホスト名をカンマ区切りで指定します。ループバックへのバインドでは、localhost、127.0.0.1、[::1] は常に許可され、それ以外の Host は拒否されます。その他のバインドでは必須です。
OECSH_MCP_ALLOW_ANY_HOST	（オフ）	1 を設定すると、ループバック以外へのバインドで任意の Host ヘッダーを許可します（この場合、DNS リバインディング対策は Origin チェックのみに依存します）
OECSH_MCP_ALLOWED_ORIGINS	（なし）	許可するブラウザーのオリジン。Origin ヘッダーのないリクエストには影響しません。
OECSH_MCP_PROXY_SECRET	（なし）	スペースを含まない、32 文字以上の印字可能な ASCII 文字列からなるシークレット（例：openssl rand -hex 32）を API と共有します。設定すると、すべての API リクエストに X-OECSH-MCP-Proxy: <secret> と X-OECSH-Client-IP: <caller's address> が付加され、API は拒否されたキーをこのサーバーではなく呼び出し元に対してカウントします。OECSH_API_URL にのみ送信され、ログに記録されず、レスポンスにも含まれません。未設定の場合、どちらのヘッダーも送信されません。まず API に同一の値を PLATFORM_MCP_PROXY_SECRET として設定してください。API 側の値が空か異なる場合、API はこれらのヘッダーを無視しますが、このサーバーはそれを検知できないため、ホスト型サービスのユーザー全員が再び同じカウントを共有することになります。これは設定可能な API に対してのみ機能します。api.oec.sh を参照するセルフホストサーバーでは、未設定のままにしてください。
OECSH_MCP_CLIENT_IP_HEADER	cf-connecting-ip	呼び出し元のアドレスを含むリクエストヘッダー。サーバーの手前にあるプロキシによって設定されます。この値が信頼されるのは、ローカルプロキシの手前にあるホップ（Traefik が追加する最後の X-Forwarded-For エントリ。接続元がプライベートアドレスまたは信頼済みプロキシの場合のみ読み取られます）が、Cloudflare が公開している範囲内、または OECSH_MCP_TRUSTED_PROXIES に含まれている場合です。それ以外の場合、または値が単一の IPv4 もしくは IPv6 アドレスではない場合、そのホップを呼び出し元のアドレスとして扱います。アドレスは統一された形式で引き渡されます（IPv6 は圧縮形式、IPv4 マップ IPv6 は IPv4 として扱います）。
OECSH_MCP_TRUSTED_PROXIES	（なし）	クライアントアドレスのヘッダーが信頼され、サーバーへ直接接続できる追加のプロキシを、アドレスまたは CIDR 範囲のカンマ区切りで指定します。

エンドポイント：POST /mcp（MCP、ステートレス、JSON レスポンス）および GET /healthz。TLS を終端し、アドレスごとの接続数を制限するプロキシの背後に配置してください。

開発

cd mcp-server
npm install
npm run build
npm test
npx @modelcontextprotocol/inspector -e OECSH_API_KEY=oec_live_ro_... node dist/stdio.js

このパッケージは、oec.sh リポジトリの他の部分に依存しません。

ライセンス

MIT。詳細は LICENSE を参照してください。Copyright (c) 2026 OpenEduCat Inc. セキュリティ上の問題を報告するには、SECURITY.md を参照してください。

Odoo は Odoo S.A. の商標です。oec.sh は Odoo S.A. とは関係ありません。