Openapi®

---

概要

openapi-mcp-sdk へようこそ。これは公式の openapi.com MCP SDKです。 PyPI のPythonパッケージとして提供されており、 次の2つの方法で使用できます。

• すぐに使えるサーバー — クローンやセットアップは不要で、単一のコマンドを使ってパッケージからMCPゲートウェイを直接実行できます。
• Pythonライブラリ — 独自のプロジェクトで openapi_mcp_sdk をインポートし、独自のロジック、ツール、認証レイヤーを追加してopenapi.com APIをラップするカスタムMCPサーバーを構築できます。

環境変数

すべての設定は環境変数を通じて行います。サーバーの起動に必須の環境変数はありません。デフォルト値はローカルでの使用に適しています。

コア

変数	デフォルト	説明
MCP_PORT	8080	サーバーがリッスンするHTTPポート
MCP_ENV	production	実行環境：dev | staging | production
MCP_BASE_URL	http://localhost:8080	このサーバーの公開URL（コールバックURLとファイルダウンロードURLの生成に使用）
MCP_CALLBACK_URL	$MCP_BASE_URL/callbacks	非同期APIに送信する明示的なコールバックURL
MCP_OPENAPI_ENV	(empty)	Openapi環境：dev、test、sandbox（test の別名）、または本番環境を表す空の値

ストレージ

会社の公式文書など、バイナリ形式のドキュメントを返すAPIでは、ファイルを保存する必要があります。ストレージバックエンドは設定できます。

変数	デフォルト	説明
MCP_STORAGE_BACKEND	local	local | gcs | s3
MCP_STORAGE_PATH	./openapi_storage	local バックエンドのローカルパス
MCP_STORAGE_BUCKET	(required for cloud)	gcs または s3 のバケット名
MCP_STORAGE_REGION	(required for s3)	S3バケットのAWSリージョン

キャッシュ

複数のサーバーインスタンス間で非同期コールバックの結果を共有するために使用します。

変数	デフォルト	説明
MCP_CACHE_BACKEND	none	none（プロセス内の dict）| memcached | redis
MCP_CACHE_URL	(none)	Redis 接続 URL（MCP_CACHE_BACKEND=redis）、例：redis://host:6379
MCP_CACHE_HOST	(none)	Memcached ホスト（MCP_CACHE_BACKEND=memcached）
MCP_CACHE_PORT	11211	Memcached ポート

環境ごとの設定ガイド（local、 Docker、AWS、GCP、Kubernetes）については、docs/env/ を参照してください。

機能

• セキュアなプロキシ：機密性の高い認証情報を直接扱うことなく、クライアントから提供された Bearer Token をそのまま転送します。
• 拡張可能：/apis/ にモジュールを作成するだけで、新しいツールや API を簡単に追加できます。
• MCP 互換：MCP プロトコルのベストプラクティスに沿って設計されています。
• モジュール式：すべての API 呼び出しロジックとツール登録を mcp_core.py に集約しています。

クイックスタート — PyPI から実行（推奨）

クローンも仮想環境も不要です。1 つのコマンドでサーバーを起動できます：

uvx openapi-mcp-sdk server

サーバーは http://localhost:8080 で直ちに起動します。

その他のランタイム

# pipx (ephemeral run, no install needed — similar to uvx)
pipx run openapi-mcp-sdk server

# pip (installs the package, then run the command)
pip install openapi-mcp-sdk && openapi-mcp-sdk server

# pip3 on systems where python3 is the default
pip3 install openapi-mcp-sdk && openapi-mcp-sdk server

CLI リファレンス

openapi-mcp-sdk <command>

Commands:
  server   Start the MCP server (HTTP/SSE, default port 8080)
  ping     Ping the openapi.com APIs and report latency       [coming soon]
  token    Generate or inspect an openapi.com Bearer token    [coming soon]

Docker で実行する

このプロジェクトには、mcp サービスを含む単一の compose.yml が用意されています。

# Build and start (production-like image)
docker compose up --build

# Run in background
docker compose up --build -d

# Follow logs
docker compose logs -f mcp

サーバーには http://localhost:8080 からアクセスできます。

デバッグと開発

ローカル開発（Docker なし）

最も素早く反復できる方法は、uvicorn でサーバーを直接実行することです：

make start

これにより PYTHONPATH=src が設定され、自動リロードを無効にして uvicorn が起動します。 サーバーは http://0.0.0.0:8080 でリクエストを待ち受けます。

エンドポイントを手動でテストするには：

curl -H "Authorization: Bearer YOUR_TOKEN" http://localhost:8080

サーバーはリクエストヘッダーとパラメーターを標準出力に表示します。追加の 設定は不要です。

VS Code と Docker によるリモートデバッグ（ワンクリック）

このリポジトリは、ワンクリックでデバッグできるよう事前設定されています。 手動での手順や compose ファイルの編集、ターミナルコマンドは不要です。

仕組み

ファイル	役割
docker/dev/Dockerfile	デバッグイメージ — debugpy を追加し、ポート 5678 を公開します
compose.yml	Compose 設定 — 開発用イメージ、デバッグポート、バインドマウントを指定します
.vscode/tasks.json	VS Code タスク — コンテナーを自動的に起動・停止します
.vscode/launch.json	起動設定 — F5 の操作ですべてを連携させます

ワークフロー

1. src/ 内の任意の場所にブレークポイントを設定します。
2. 実行とデバッグ（Ctrl+Shift+D / ⌘+Shift+D）を開きます。
3. ドロップダウンから MCP: Debug (Docker) を選択します。
4. F5 を押します。

VS Code は次の処理を行います：

• 必要に応じてデバッグイメージ（docker/dev/Dockerfile）をビルドします。
• compose.yml を使ってコンテナーを起動します（デバッグイメージ＋バインドマウント）。
• debugpy がポート 5678 で接続を受け付けるまで自動的に待機します。
• debugpy にアタッチします。これでブレークポイントが有効になります。

⇧F5（停止）を押すと、VS Code はデタッチしてコンテナーを終了します。

デタッチした後もコンテナーを起動したままにしますか？ .vscode/launch.json から "postDebugTask" の行を削除してください。その後は、再ビルドせずに F5 をもう一度押すだけでいつでも再アタッチできます。

ライブコードリロード

compose.yml は、ホストの ./src をコンテナー内の /app/src にバインドマウントします。 src/ 内のファイルを編集すると、即座に反映されます。イメージの再ビルドは 不要です。新しいリクエストを送信するだけで、更新されたコードが実行されます。

パスマッピングのリファレンス

	ホスト	コンテナー
ソースコード	./src	/app/src
MCP サーバー	localhost:8080	0.0.0.0:8080
debugpy リスナー	localhost:5678	0.0.0.0:5678

認証

サーバーは次の 2 つの方法で Bearer token を受け付けます：

オプション A — Authorization ヘッダー（推奨）

標準の HTTP ヘッダーとしてトークンを渡します：

Authorization: Bearer YOUR_TOKEN

オプション B — ?token= クエリパラメーター

一部の MCP クライアントや環境では、カスタム HTTP ヘッダーがサポートされていません。その 場合、トークンをクエリパラメーターとしてサーバー URL に直接埋め込めます。

http://YOUR_SERVER_IP:8080/?token=YOUR_TOKEN

リクエストが MCP レイヤーに到達する前に、サーバーが自動的にトークンを Authorization: Bearer ヘッダーに設定するため、動作は同じです。

?token= を使用する場合： Claude Desktop（2025 年半ば時点）、一部のブラウザーベースの MCP プレイグラウンド、ヘッダーフィールドのないプレーンな URL のみを受け付ける設定のクライアント。

MCP クライアントの設定（VS Code）

1. Bearer Token を生成する ポータル https://console.openapi.com/oauth から、必要なスコープを指定してトークンを作成します。

2. .vscode/mcp.json ファイルを作成する

   ヘッダーを使用（推奨）：

   {
     "servers": {
       "openapi.com": {
         "type": "http",
         "url": "http://YOUR_SERVER_IP:8080/",
         "headers": {
           "Authorization": "Bearer YOUR_TOKEN"
         }
       }
     }
   }
   

   ?token= クエリパラメーターを使用（カスタムヘッダーをサポートしないクライアント向け）：

   {
     "servers": {
       "openapi.com": {
         "type": "http",
         "url": "http://YOUR_SERVER_IP:8080/?token=YOUR_TOKEN"
       }
     }
   }
   

3. 連携をテストする

   • VS Code を再読み込みします。
   • Copilot チャットを開き、@workspace と入力します。
   • MCP サーバーが公開するツールを使用します。

ファイルストレージ

一部の openapi.com API（例：visure camerali — イタリアの公式企業文書）は、 MCP ストリームにインラインで埋め込めない大容量のバイナリファイル（ZIP アーカイブ、PDF）を返します。サーバーはこれらのファイルをダウンロードして保存し、 別の HTTP エンドポイント（GET /status/{id}/files/{filename}）経由で提供します。

デフォルト：ローカルファイルシステム

デフォルト（MCP_STORAGE_BACKEND=local）では、サーバーの起動元ディレクトリを基準に ./openapi_storage へファイルを書き込みます。

./openapi_storage/
└── <request_id>/
    ├── document.pdf
    └── attachments.zip

MCP_STORAGE_PATH 環境変数でパスを上書きします。

export MCP_STORAGE_PATH=/var/data/openapi_storage
uvx openapi-mcp-sdk server

ディレクトリは初回使用時に自動作成されます。ダウンロードリンクを 正しく機能させるには、MCP_BASE_URL をサーバーのパブリックアドレスに設定する必要があります （デフォルト：http://localhost:8080）。

クラウドストレージのバックエンド

MCP_STORAGE_BACKEND	追加の変数	備考
local	MCP_STORAGE_PATH（デフォルト ./openapi_storage）	デフォルト — ローカルディスクまたはマウントされたボリューム
gcs	MCP_STORAGE_BUCKET	Google Cloud Storage
s3	MCP_STORAGE_BUCKET、MCP_STORAGE_REGION	AWS S3 または S3 互換サービス

環境ごとの詳しい設定ガイドについては、docs/env/ を参照してください。

デプロイ環境

環境	ガイド
ローカルマシン（デフォルト）	docs/env/local.md
Docker / Docker Compose	docs/env/docker.md
Google Cloud Platform	docs/env/gcp.md
Amazon Web Services	docs/env/aws.md
Kubernetes	docs/env/kubernetes.md

プロジェクト構成

• src/openapi_mcp_sdk/main.py：FastAPI + MCP サーバーのエントリーポイント。
• src/openapi_mcp_sdk/mcp_core.py：MCP の初期化、API 呼び出しヘルパー、エラー処理。
• src/openapi_mcp_sdk/apis/：MCP ツールを定義する Python モジュール（API／スコープごとに 1 つ）。
• requirements.txt：Python の依存関係。
• compose.yml：Docker Compose（デフォルトは本番イメージ。デバッグ用に切り替える方法はコメントを参照）。
• docker/latest/Dockerfile：本番用 Docker イメージ。
• docker/dev/Dockerfile：VS Code のリモートデバッグ用に debugpy を含む開発イメージ。
• .vscode/launch.json：VS Code のデバッグ設定（debugpy に接続）。
• docs/：ドキュメントと設定例。

新しいツール／API の追加

1. 次のパターンに従って、/apis/ にファイルを作成または変更します。

   from fastmcp import Context
   from typing import Any
   from mcp_core import make_api_call, mcp
   
   @mcp.tool
   async def tool_name(parameters..., ctx: Context) -> Any:
       # ...logic...
       return make_api_call(ctx, "GET", url, params=params)
   

2. 変更を適用するには、サーバーを再起動します。

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

• 認証情報やトークンをコードにハードコードしないでください。
• サーバーは、クライアントから HTTP ヘッダー経由で Bearer Token が提供されることを想定しています。
• すべての API 呼び出しは、クライアントから提供されたトークンを使用してプロキシされます。

便利なリソース

• MCP ドキュメント
• fastmcp
• openapi.com

コントリビューション

コントリビューションはいつでも歓迎します！バグの報告、新機能の提案、ドキュメントの改善、コードへの貢献など、皆さまのご協力に感謝します。

始め方の詳しい手順については、docs/contributing.mdをご覧ください。温かく協力的な環境を維持できるよう、このプロジェクトのdocs/code-of-conduct.mdに従ってください。

著者

プロジェクトの著者をご紹介します。

• Simone Desantis (@SimoneDesantis)
• Marco Prosperi (@MarcoProsperi)
• Francesco Bianco (@francescobianco)
• Openapi Team (@openapi-it)

パートナー

Openapi を利用している、またはこの SDK に貢献しているパートナーをご紹介します。

• Blank
• Credit Safe
• Deliveroo
• Gruppo MOL
• Jakala
• Octotelematics
• OTOQI
• PWC
• QOMODO S.R.L.
• SOUNDREEF S.P.A.

ライセンス

このプロジェクトはMIT Licenseのもとでライセンスされています。

MIT License は寛容なオープンソースライセンスで、元の著作権表示とこの許諾表示をソフトウェアのすべてのコピーまたは実質的な部分に含めることを条件に、ソフトウェアを自由に使用、複製、変更、結合、公開、配布、サブライセンス、および／または販売できます。

つまり、この SDK は個人、学術、商用のプロジェクトで、最小限の制約のもと自由に使用できます。このプロジェクトは「現状有姿」で提供され、明示的か黙示的かを問わず、商品性、特定目的への適合性、非侵害性の保証を含むいかなる種類の保証もありません。

詳細については、MIT License ページにあるライセンス全文をご覧ください。