OpenAPI MCP サーバー

OpenAPIエンドポイントをMCPリソースとして公開するモデルコンテキストプロトコル（MCP）サーバー。このサーバーにより、大規模言語モデルはMCPプロトコルを介してOpenAPI仕様で定義されたREST APIを検出し、操作できるようになります。

概要

この MCP サーバーは、次の 2 つのトランスポート方法をサポートしています。

1. Stdio トランスポート(デフォルト): 標準入出力を介して MCP 接続を管理する Claude Desktop などの AI システムと直接統合します。

2. ストリーミング可能な HTTP トランスポート: HTTP 経由でサーバーに接続し、Web クライアントやその他の HTTP 対応システムが MCP プロトコルを使用できるようにします。

Related MCP server: MCP OpenAPI Server

ユーザー向けクイックスタート

オプション 1: Claude Desktop (Stdio トランスポート) を使用する

このリポジトリをクローンする必要はありません。Claude Desktop をこの MCP サーバーを使用するように設定するだけで済みます。

1. Claude Desktop 構成ファイルを見つけるか作成します。

   • macOSの場合: ~/Library/Application Support/Claude/claude_desktop_config.json

2. 次の構成を追加します。

{
  "mcpServers": {
    "openapi": {
      "command": "npx",
      "args": ["-y", "@ivotoby/openapi-mcp-server"],
      "env": {
        "API_BASE_URL": "https://api.example.com",
        "OPENAPI_SPEC_PATH": "https://api.example.com/openapi.json",
        "API_HEADERS": "Authorization:Bearer token123,X-API-Key:your-api-key"
      }
    }
  }
}

3. 環境変数を実際の API 構成に置き換えます。

   • API_BASE_URL : APIのベースURL

   • OPENAPI_SPEC_PATH : OpenAPI 仕様への URL またはパス

   • API_HEADERS : API認証ヘッダーのコンマ区切りのキーと値のペア

オプション 2: HTTP クライアント (HTTP トランスポート) で使用する

HTTP クライアントでサーバーを使用するには:

1. インストールは不要です！npx を使用してパッケージを直接実行します。

npx @ivotoby/openapi-mcp-server \
  --api-base-url https://api.example.com \
  --openapi-spec https://api.example.com/openapi.json \
  --headers "Authorization:Bearer token123" \
  --transport http \
  --port 3000

2. HTTP リクエストを使用してサーバーと対話します。

# Initialize a session (first request)
curl -X POST http://localhost:3000/mcp \
  -H "Content-Type: application/json" \
  -d '{"jsonrpc":"2.0","id":0,"method":"initialize","params":{"client":{"name":"curl-client","version":"1.0.0"},"protocol":{"name":"mcp","version":"2025-03-26"}}}'

# The response includes a Mcp-Session-Id header that you must use for subsequent requests
# and the InitializeResult directly in the POST response body.

# Send a request to list tools
# This also receives its response directly on this POST request.
curl -X POST http://localhost:3000/mcp \
  -H "Content-Type: application/json" \
  -H "Mcp-Session-Id: your-session-id" \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/list"}'

# Open a streaming connection for other server responses (e.g., tool execution results)
# This uses Server-Sent Events (SSE).
curl -N http://localhost:3000/mcp -H "Mcp-Session-Id: your-session-id"

# Example: Execute a tool (response will arrive on the GET stream)
# curl -X POST http://localhost:3000/mcp \
#  -H "Content-Type: application/json" \
#  -H "Mcp-Session-Id: your-session-id" \
#  -d '{"jsonrpc":"2.0","id":2,"method":"tools/execute","params":{"name":"yourToolName", "arguments": {}}}'

# Terminate the session when done
curl -X DELETE http://localhost:3000/mcp -H "Mcp-Session-Id: your-session-id"

輸送タイプ

標準入出力トランスポート（デフォルト）

stdioトランスポートは、標準入出力を介してMCP接続を管理するClaude DesktopなどのAIシステムと直接統合するために設計されています。これは最もシンプルなセットアップであり、ネットワーク設定は必要ありません。

使用する場合: Claude Desktop または stdio ベースの MCP 通信をサポートする他のシステムと統合する場合。

ストリーミング可能なHTTPトランスポート

HTTPトランスポートにより、MCPサーバーにHTTP経由でアクセスすることが可能になり、Webアプリケーションやその他のHTTP対応クライアントがMCPプロトコルとやり取りできるようになります。セッション管理、ストリーミングレスポンス、標準HTTPメソッドをサポートしています。

主な機能:

• Mcp-Session-Idヘッダーによるセッション管理

• initializeおよびtools/list要求に対する HTTP 応答は、POST で同期的に送信されます。

• その他のサーバーからクライアントへのメッセージ (例: tools/execute結果、通知) は、Server-Sent Events (SSE) を使用して GET 接続を介してストリーミングされます。

• POST/GET/DELETEメソッドのサポート

使用する場合: MCP サーバーを、stdio ではなく HTTP 経由で通信する Web クライアントまたはシステムに公開する必要がある場合。

設定オプション

サーバーは、環境変数またはコマンドライン引数を使用して構成できます。

環境変数

• API_BASE_URL - APIエンドポイントのベースURL

• OPENAPI_SPEC_PATH - OpenAPI 仕様へのパスまたは URL

• API_HEADERS - APIヘッダーのコンマ区切りのキーと値のペア

• SERVER_NAME - MCP サーバーの名前 (デフォルト: "mcp-openapi-server")

• SERVER_VERSION - サーバーのバージョン（デフォルト: "1.0.0"）

• TRANSPORT_TYPE - 使用するトランスポートタイプ: "stdio" または "http" (デフォルト: "stdio")

• HTTP_PORT - HTTPトランスポートのポート（デフォルト: 3000）

• HTTP_HOST - HTTPトランスポートのホスト（デフォルト: "127.0.0.1"）

• ENDPOINT_PATH - HTTPトランスポートのエンドポイントパス（デフォルト: "/mcp"）

コマンドライン引数

npx @ivotoby/openapi-mcp-server \
  --api-base-url https://api.example.com \
  --openapi-spec https://api.example.com/openapi.json \
  --headers "Authorization:Bearer token123,X-API-Key:your-api-key" \
  --name "my-mcp-server" \
  --version "1.0.0" \
  --transport http \
  --port 3000 \
  --host 127.0.0.1 \
  --path /mcp

セキュリティに関する考慮事項

• HTTPトランスポートは、DNSリバインディング攻撃を防ぐためにOriginヘッダーを検証します。

• デフォルトでは、HTTPトランスポートはローカルホスト（127.0.0.1）にのみバインドされます。

• 他のホストに公開する場合は、追加の認証を実装することを検討してください

デバッグ

デバッグ ログを表示するには:

1. Claude Desktop で stdio トランスポートを使用する場合:

   • ログはClaude Desktopのログに表示されます

2. HTTP トランスポートを使用する場合:

   npx @ivotoby/openapi-mcp-server --transport http 2>debug.log

開発者向け

開発ツール

• npm run build - TypeScriptソースをビルドする

• npm run clean - ビルド成果物を削除します

• npm run typecheck - TypeScript の型チェックを実行します

• npm run lint - ESLint を実行する

• npm run dev - ソースファイルを監視し、変更があったら再構築する

• npm run inspect-watch - 変更時に自動リロードするインスペクターを実行します

開発ワークフロー

1. リポジトリをクローンする

2. 依存関係をインストール: npm install

3. 開発環境を起動します: npm run inspect-watch

4. src/内の TypeScript ファイルに変更を加える

5. サーバーは自動的に再構築され、再起動します

貢献

1. リポジトリをフォークする

2. 機能ブランチを作成する

3. 変更を加える

4. テストとリンティングを実行します: npm run typecheck && npm run lint

5. プルリクエストを送信する

ライセンス

マサチューセッツ工科大学