OpenAPI-MCP: Dockerized MCP Server to allow your AI agent to access any API with existing api docs

OpenAPI-MCP：既存の API ドキュメントを使い、AI エージェントがあらゆる API にアクセスできる Docker 化 MCP サーバー

Swagger/OpenAPI 仕様ファイルから MCP ツール定義を直接生成します。

OpenAPI-MCP は、swagger.json または openapi.yaml ファイルを読み込み、対応する Model Context Protocol (MCP) ツールセットを生成する、Docker 化された MCP サーバーです。これにより、Cursor などの MCP 対応クライアントが、標準的な OpenAPI 仕様で記述された API を利用できるようになります。OpenAPI/Swagger 仕様を用意するだけで、追加のコーディングなしに AI エージェントがあらゆる API にアクセスできるようになります。

目次

• OpenAPI-MCP を選ぶ理由
• 機能
• インストール
  • Docker Hub のビルド済みイメージを使用する（推奨）
  • ローカルでビルドする（任意）
• Weatherbit の例を実行する（ステップごとの手順）
• コマンドラインオプション
  • 環境変数

デモ

自分でデモを実行する：Weatherbit の例を実行する（ステップごとの手順）

OpenAPI-MCP を選ぶ理由

• 標準への準拠： 既存の OpenAPI/Swagger ドキュメントを活用できます。
• ツールの自動生成： エンドポイントごとの手動設定なしに MCP ツールを作成できます。
• 柔軟な API キー管理： API キーを MCP クライアントに公開せず、プロキシ対象 API の API キー認証を安全に管理できます。
• ローカルおよびリモートの仕様： ローカルの仕様ファイルとリモート URL のどちらにも対応します。
• Docker 化されたツール： Docker でコンテナ化されたサービスとして、簡単にデプロイして実行できます。

機能

• OpenAPI v2（Swagger）および v3 に対応： 標準的な仕様形式を解析します。
• スキーマ生成： OpenAPI の操作パラメーターとリクエスト／レスポンス定義から MCP ツールのスキーマを作成します。
• API キーの安全な管理：
  • コマンドライン設定に基づいて、API キーをリクエスト（header、query、path、cookie）に挿入します。
    • API キーはフラグ（--api-key）、環境変数（--api-key-env）、またはローカル仕様ファイルと同じ場所にある .env ファイルから直接読み込みます。
    • API キーをエンド MCP クライアント（例：AI アシスタント）から隠します。
• サーバー URL の検出： 仕様内のサーバー URL をツール連携のベースとして使用します（上書き可能）。
• フィルタリング： 特定の操作またはタグを対象に含める／除外するオプションがあります（--include-tag、--exclude-tag、--include-op、--exclude-op）。
• リクエストヘッダーの挿入： REQUEST_HEADERS 環境変数を使用して、カスタムヘッダー（追加の認証情報やトレーシングなど）を渡せます。

インストール

Docker

このツールの実行には、Docker を使用する方法を推奨します。

Docker Hub のビルド済みイメージを使用する（推奨）

代わりに、Docker Hub で公開されているビルド済みイメージを使用できます。

1. イメージを取得する：

   docker pull ckanthony/openapi-mcp:latest
   

2. コンテナを実行する： 上記の docker run の例に従い、openapi-mcp:latest を ckanthony/openapi-mcp:latest に置き換えてください。

ローカルでビルドする（任意）

1. Docker イメージをローカルでビルドする：

   # Navigate to the repository root
   cd openapi-mcp
   # Build the Docker image (tag it as you like, e.g., openapi-mcp:latest)
   docker build -t openapi-mcp:latest .
   

2. コンテナを実行する： コンテナの実行時に、OpenAPI 仕様と必要な API キー設定を指定する必要があります。

   • 例 1：ローカルの仕様ファイルと .env ファイルを使用する場合：

     • openapi.json または swagger.yaml を含むディレクトリ（例：./my-api）を作成します。
     • API キーが必要な場合は、同じディレクトリ（例：./my-api/.env）に API_KEY=your_actual_key を記述した .env ファイルを作成します（--api-key-env フラグが異なる場合は、API_KEY を置き換えてください）。

     docker run -p 8080:8080 --rm \\
         -v $(pwd)/my-api:/app/spec \\
         --env-file $(pwd)/my-api/.env \\
         openapi-mcp:latest \\
         --spec /app/spec/openapi.json \\
         --api-key-env API_KEY \\
         --api-key-name X-API-Key \\
         --api-key-loc header
     

     (--spec、--api-key-env、--api-key-name、--api-key-loc、-p は必要に応じて調整してください。)

   • 例 2：リモートの仕様 URL と直接指定する環境変数を使用する場合：

     docker run -p 8080:8080 --rm \\
         -e SOME_API_KEY="your_actual_key" \\
         openapi-mcp:latest \\
         --spec https://petstore.swagger.io/v2/swagger.json \\
         --api-key-env SOME_API_KEY \\
         --api-key-name api_key \\
         --api-key-loc header
     

   • Docker の実行オプション：

     • -p <host_port>:8080：ホストのポートを、コンテナのデフォルトポート 8080 に割り当てます。
     • --rm：コンテナの終了時にコンテナを自動的に削除します。
     • -v <host_path>:<container_path>：仕様を含むローカルディレクトリをコンテナにマウントします。絶対パスまたは $(pwd)/... を使用してください。コンテナ内の一般的なパスは /app/spec です。
     • --env-file <path_to_host_env_file>：ローカルファイルから環境変数を読み込みます（API キーなど）。パスはホスト上のものです。
     • -e <VAR_NAME>="<value>"：単一の環境変数を直接渡します。
     • openapi-mcp:latest：ローカルでビルドしたイメージの名前です。
     • --spec ...：必須です。 コンテナ内の仕様ファイルのパス（例：/app/spec/openapi.json）または公開 URL を指定します。
     • --port 8080：（任意）サーバーがリッスンする内部ポートを変更します（-p のコンテナポートと一致させる必要があります）。
     • --api-key-env、--api-key-name、--api-key-loc：対象の API で API キーが必要な場合は必須です。
     • （すべてのコマンドラインオプションについては、docker run --rm openapi-mcp:latest --help を実行して --help を参照してください。）

Weatherbit の例を実行する（ステップごとの手順）

このリポジトリには、Weatherbit API を使用する例が含まれています。公開 Docker イメージを使用して実行する方法は次のとおりです。

1. OpenAPI 仕様を見つける（任意の知識）： 多くの公開 API では、OpenAPI／Swagger 仕様をオンラインで入手できます。見つけるための優れたリソースとして、APIs.guru があります。この例で使用している Weatherbit の仕様（weatherbitio-swagger.json）も、そこから取得しました。

2. Weatherbit API キーを取得する：

   • Weatherbit.io にアクセスしてアカウントを登録します（無料プランがあります）。
   • Weatherbit アカウントのダッシュボードで API キーを確認します。

3. このリポジトリをクローンする： このリポジトリにあるサンプルファイルが必要です。

   git clone https://github.com/ckanthony/openapi-mcp.git
   cd openapi-mcp
   

4. 環境ファイルを準備する：

   • サンプルディレクトリに移動します：cd example/weather
   • サンプル環境ファイルをコピーします：cp .env.example .env
   • 新しい .env ファイルを編集し、YOUR_WEATHERBIT_API_KEY_HERE を Weatherbit から取得した実際の API キーに置き換えます。

5. Docker コンテナを実行する： openapi-mcp のルートディレクトリ（example フォルダーがあるディレクトリ）から、次のコマンドを実行します。

   docker run -p 8080:8080 --rm \\
       -v $(pwd)/example/weather:/app/spec \\
       --env-file $(pwd)/example/weather/.env \\
       ckanthony/openapi-mcp:latest \\
       --spec /app/spec/weatherbitio-swagger.json \\
       --api-key-env API_KEY \\
       --api-key-name key \\
       --api-key-loc query
   

   • -v $(pwd)/example/weather:/app/spec：ローカルの example/weather ディレクトリ（仕様ファイルと .env ファイルを含む）を、コンテナ内の /app/spec にマウントします。
   • --env-file $(pwd)/example/weather/.env：Docker に .env ファイルから環境変数（特に API_KEY）を読み込ませます。
   • ckanthony/openapi-mcp:latest：公開 Docker イメージを使用します。
   • --spec /app/spec/weatherbitio-swagger.json：コンテナ内の仕様ファイルを指定します。
   • --api-key-* フラグは、ツールが API キーをどのように挿入するかを設定します（API_KEY 環境変数から読み取り、名前を key とし、query 文字列に配置します）。

6. MCP サーバーにアクセスする： MCP サーバーが起動し、互換性のあるクライアントから http://localhost:8080 でアクセスできるようになります。

Docker Compose を使用する（例）：

Weatherbit API の例をローカルでビルドしたイメージを使用して実行する方法を示す docker-compose.yml ファイルが、example/ ディレクトリに用意されています。

1. 環境ファイルを準備する： example/weather/.env.example を example/weather/.env にコピーし、実際の Weatherbit API キーを追加します。

   # example/weather/.env
   API_KEY=YOUR_ACTUAL_WEATHERBIT_KEY
   

2. Docker Compose で実行する： example ディレクトリに移動し、次を実行します。

   cd example
   # これは ../Dockerfile に基づいてイメージをローカルでビルドします
   # 公開 Docker Hub イメージは使用しません
   docker-compose up --build
   

   • --build：サービスを開始する前に、Docker Compose にプロジェクトルートの Dockerfile を使用してイメージをビルドさせます。
   • Compose は example/docker-compose.yml を読み込み、イメージをビルドし、./weather をマウントして ./weather/.env を読み込み、指定されたコマンドライン引数で openapi-mcp コンテナを起動します。
   • MCP サーバーには http://localhost:8080 でアクセスできます。

3. サービスを停止する： Compose を実行しているターミナルで Ctrl+C を押すか、別のターミナルから example ディレクトリで docker-compose down を実行します。

コマンドラインオプション

openapi-mcp コマンドでは、次のフラグを使用できます。

フラグ	説明	型	デフォルト
--spec	必須。 OpenAPI 仕様ファイルのパスまたは URL です。	string	(none)
--port	MCP サーバーを実行するポートです。	int	8080
--api-key	API キーの値を直接指定します（セキュリティのため、代わりに --api-key-env または .env ファイルを使用してください）。	string	(none)
--api-key-env	API キーを含む環境変数名です。仕様ファイルがローカルにある場合は、仕様ファイルのディレクトリにある .env ファイルも確認します。	string	(none)
--api-key-name	キーを使用する場合は必須。 API キーパラメーターの名前（ヘッダー、クエリ、パス、または Cookie の名前）です。	string	(none)
--api-key-loc	キーを使用する場合は必須。 API キーの場所です。header、query、path、または cookie を指定します。	string	(none)
--include-tag	含めるタグです（繰り返し指定できます）。include フラグを使用すると、指定した項目のみが公開されます。	string slice	(none)
--exclude-tag	除外するタグです（繰り返し指定できます）。除外は包含の後に適用されます。	string slice	(none)
--include-op	含める Operation ID です（繰り返し指定できます）。	string slice	(none)
--exclude-op	除外する Operation ID です（繰り返し指定できます）。	string slice	(none)
--base-url	仕様から検出された接続先 API サーバーのベース URL を手動で上書きします。	string	(none)
--name	生成する MCP ツールセットのデフォルト名です（仕様にタイトルがない場合に使用されます）。	string	"OpenAPI-MCP Tools"
--desc	生成する MCP ツールセットのデフォルトの説明です（仕様に説明がない場合に使用されます）。	string	"Tools generated from OpenAPI spec"

注： ツールに --help フラグを付けて実行すると、この一覧を表示できます（例：docker run --rm ckanthony/openapi-mcp:latest --help）。

環境変数

• REQUEST_HEADERS：この環境変数に JSON 文字列（例：'{"X-Custom": "Value"}'）を設定すると、接続先 API へのすべての送信リクエストにカスタムヘッダーが追加されます。