OpenAPIからMCPサーバーへ

OpenAPI/Swagger仕様からMCP（Model Context Protocol）サーバーを作成し、AIアシスタントがAPIを操作できるようにするツールです。特定のAPIやサービス向けに**、独自のブランドでカスタマイズされたMCPを作成できます**。

概要

このプロジェクトは、OpenAPI仕様をMCPツールに変換する動的MCPサーバーを構築します。モデルコンテキストプロトコル（MCP）を介してREST APIとAIアシスタントをシームレスに統合し、あらゆるAPIをAIがアクセス可能なツールに変換します。

特徴

ファイルまたは HTTP/HTTPS URL からの OpenAPI 仕様の動的読み込み
ファイルまたは HTTP/HTTPS URL から読み込まれたOpenAPI オーバーレイのサポート
OpenAPI 操作と MCP ツールのマッピングをカスタマイズ可能
オペレーションIDとURLパスの両方にglobパターンを使用した高度な操作フィルタリング
フォーマットの保存と位置メタデータによる包括的なパラメータ処理
API認証処理
MCP サーバーを構成するために使用される OpenAPI メタデータ (タイトル、バージョン、説明)
階層的な記述フォールバック（操作記述 → 操作概要 → パス概要）
環境変数と CLI によるカスタム HTTP ヘッダーのサポート
APIリクエストの追跡と識別のためのX-MCPヘッダー
ツール名と説明を上書きするためのパスレベルでのカスタムx-mcp拡張機能のサポート

AIアシスタントと併用する

このツールは、AIアシスタントがOpenAPI仕様で定義されたAPIと連携できるようにするMCPサーバーを作成します。主な使用方法は、AIアシスタントをMCPツールとして直接実行するように設定することです。

Claude Desktopでの設定

コンピュータにNode.jsがインストールされていることを確認してください
Claude Desktopを開き、「設定」>「開発者」に移動します。
設定ファイルを編集します (存在しない場合は作成されます)。
- macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
- Windows: %APPDATA%\Claude\claude_desktop_config.json
次の構成を追加します (必要に応じてカスタマイズします)。

{
  "mcpServers": {
    "api-tools": {
      "command": "npx",
      "args": [
        "-y",
        "@tyktechnologies/api-to-mcp",
        "--spec",
        "https://petstore3.swagger.io/api/v3/openapi.json"
      ],
      "enabled": true
    }
  }
}

Claudeデスクトップを再起動します
チャット入力ボックスにハンマーアイコンが表示されます。クリックしてAPIツールにアクセスしてください。

設定のカスタマイズ

args配列を調整して、さまざまなオプションを使用して MCP サーバーをカスタマイズできます。

{
  "mcpServers": {
    "my-api": {
      "command": "npx",
      "args": [
        "-y",
        "@tyktechnologies/api-to-mcp",
        "--spec",
        "./path/to/your/openapi.json",
        "--overlays",
        "./path/to/overlay.json,https://example.com/api/overlay.json",
        "--whitelist",
        "getPet*,POST:/users/*",
        "--targetUrl",
        "https://api.example.com"
      ],
      "enabled": true
    }
  }
}

カーソルでの設定

次のいずれかの場所に構成ファイルを作成します。
- プロジェクト固有: プロジェクトディレクトリ内の.cursor/mcp.json
- グローバル: ホームディレクトリの~/.cursor/mcp.json
次の構成を追加します (API に合わせて必要に応じて調整してください)。

{
  "servers": [
    {
      "command": "npx",
      "args": [
        "-y",
        "@tyktechnologies/api-to-mcp",
        "--spec",
        "./path/to/your/openapi.json"
      ],
      "name": "My API Tools"
    }
  ]
}

カーソルを再起動するか、ウィンドウを再読み込みします

Vercel AI SDKを使用する

Vercel AI SDK の MCP クライアントを使用して、この MCP サーバーを JavaScript/TypeScript アプリケーションで直接使用することもできます。

import { experimental_createMCPClient } from 'ai';
import { Experimental_StdioMCPTransport } from 'ai/mcp-stdio';
import { generateText } from 'ai';
import { createGoogleGenerativeAI } from '@ai-sdk/google';

// Initialize the Google Generative AI provider
const google = createGoogleGenerativeAI({
  apiKey: process.env.GOOGLE_API_KEY, // Set your API key in environment variables
});
const model = google('gemini-2.0-flash');

// Create an MCP client with stdio transport
const mcpClient = await experimental_createMCPClient({
  transport: {
    type: 'stdio',
    command: 'npx', // Command to run the MCP server
    args: ['-y', '@tyktechnologies/api-to-mcp', '--spec', 'https://petstore3.swagger.io/api/v3/openapi.json'], // OpenAPI spec
    env: {
      // You can set environment variables here
      // API_KEY: process.env.YOUR_API_KEY,
    },
  },
});

async function main() {
  try {
    // Retrieve tools from the MCP server
    const tools = await mcpClient.tools();

    // Generate text using the AI SDK with MCP tools
    const { text } = await generateText({
      model,
      prompt: 'List all available pets in the pet store using the API.',
      tools, // Pass the MCP tools to the model
    });

    console.log('Generated text:', text);
  } catch (error) {
    console.error('Error:', error);
  } finally {
    // Always close the MCP client to release resources
    await mcpClient.close();
  }
}

main();

構成

構成は、環境変数、コマンドラインオプション、または JSON 構成ファイルを介して管理されます。

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

# Start with specific OpenAPI spec file
@tyktechnologies/api-to-mcp --spec=./path/to/openapi.json

# Apply overlays to the spec
@tyktechnologies/api-to-mcp --spec=./path/to/openapi.json --overlays=./path/to/overlay.json,https://example.com/api/overlay.json

# Include only specific operations (supports glob patterns)
@tyktechnologies/api-to-mcp --spec=./path/to/openapi.json --whitelist="getPet*,POST:/users/*"

# Specify target API URL
@tyktechnologies/api-to-mcp --spec=./path/to/openapi.json --targetUrl=https://api.example.com

# Add custom headers to all API requests
@tyktechnologies/api-to-mcp --spec=./path/to/openapi.json --headers='{"X-Api-Version":"1.0.0"}'

# Disable the X-MCP header
@tyktechnologies/api-to-mcp --spec=./path/to/openapi.json --disableXMcp

環境変数

これらは.envファイルで設定することも、環境内で直接設定することもできます。

OPENAPI_SPEC_PATH : OpenAPI 仕様ファイルへのパス
OPENAPI_OVERLAY_PATHS : JSON ファイルをオーバーレイするためのコンマ区切りのパス
TARGET_API_BASE_URL : API呼び出しのベースURL（OpenAPIサーバーをオーバーライド）
MCP_WHITELIST_OPERATIONS : 含める操作IDまたはURLパスのカンマ区切りリスト（ getPet*やGET:/pets/*などのglobパターンをサポート）
MCP_BLACKLIST_OPERATIONS : 除外する操作IDまたはURLパスのカンマ区切りリスト（globパターンをサポート、ホワイトリストが使用されている場合は無視されます）
API_KEY : 対象APIのAPIキー（必要な場合）
SECURITY_SCHEME_NAME : APIキーを必要とするセキュリティスキームの名前
SECURITY_CREDENTIALS : 複数のスキームのセキュリティ資格情報を含むJSON文字列
CUSTOM_HEADERS : すべてのAPIリクエストに含めるカスタムヘッダーを含むJSON文字列
HEADER_* : HEADER_で始まる環境変数はカスタムヘッダーとして追加されます (例: HEADER_X_API_Version=1.0.0ヘッダーX-API-Version: 1.0.0を追加します)
DISABLE_X_MCP : trueに設定すると、すべてのAPIリクエストにX-MCP: 1ヘッダーを追加できなくなります。
CONFIG_FILE : JSON設定ファイルへのパス

JSON構成

環境変数やコマンドラインオプションの代わりに、JSON設定ファイルを使用することもできます。MCPサーバーは以下の順序で設定ファイルを検索します。

--configコマンドラインオプションで指定されたパス
CONFIG_FILE環境変数で指定されたパス
現在のディレクトリのconfig.json
現在のディレクトリにあるopenapi-mcp.json
現在のディレクトリの.openapi-mcp.json

JSON 構成ファイルの例:

{
  "spec": "./path/to/openapi-spec.json",
  "overlays": "./path/to/overlay1.json,https://example.com/api/overlay.json",
  "targetUrl": "https://api.example.com",
  "whitelist": "getPets,createPet,/pets/*",
  "blacklist": "deletePet,/admin/*",
  "apiKey": "your-api-key",
  "securitySchemeName": "ApiKeyAuth",
  "securityCredentials": {
    "ApiKeyAuth": "your-api-key",
    "OAuth2": "your-oauth-token"
  },
  "headers": {
    "X-Custom-Header": "custom-value",
    "User-Agent": "OpenAPI-MCP-Client/1.0"
  },
  "disableXMcp": false
}

説明コメント付きの完全なサンプル構成ファイルは、ルートディレクトリのconfig.example.jsonにあります。

構成の優先順位

構成設定は、次の優先順位（最高から最低）で適用されます。

コマンドラインオプション
環境変数
JSON設定ファイル

発達

インストール

# Clone the repository
git clone <repository-url>
cd openapi-to-mcp-generator

# Install dependencies
npm install

# Build the project
npm run build

ローカルテスト

# Start the MCP server
npm start

# Development mode with auto-reload
npm run dev

独自のバージョンをカスタマイズして公開する

このリポジトリをベースに、OpenAPI to MCPサーバーを独自にカスタマイズして作成できます。このセクションでは、リポジトリをフォークし、特定のAPIに合わせてカスタマイズし、パッケージとして公開する方法について説明します。

フォークとカスタマイズ

リポジトリをフォークする: GitHub でこのリポジトリをフォークして、カスタマイズできる独自のコピーを作成します。
OpenAPI 仕様を追加します:
# Create a specs directory if it doesn't exist mkdir -p specs # Add your OpenAPI specifications cp path/to/your/openapi-spec.json specs/ # Add any overlay files cp path/to/your/overlay.json specs/
デフォルト設定を構成する: パッケージにバンドルされるカスタム構成ファイルを作成します。
# Copy the example config cp config.example.json config.json # Edit the config to point to your bundled specs # and set any default settings
package.json を更新します:
{ "name": "your-custom-mcp-server", "version": "1.0.0", "description": "Your customized MCP server for specific APIs", "files": [ "dist/**/*", "config.json", "specs/**/*", "README.md" ] }
仕様がバンドルされていることを確認する: package.json のfilesフィールド (上記に表示) により、公開されたパッケージに仕様と構成ファイルが含まれるようになります。

GitHubワークフローのカスタマイズ

このリポジトリには、npmへの自動公開のためのGitHub Actionsワークフローが含まれています。フォークしたリポジトリに合わせてカスタマイズするには、以下の手順を実行してください。

ワークフロー名を更新します。必要に応じて.github/workflows/publish-npm.yamlを編集して名前を更新します。
name: Publish My Custom MCP Package
パッケージスコープを設定する (必要な場合) : npm 組織スコープで公開する場合は、ワークフローファイルのスコープ行のコメントを解除して変更します。
- name: Setup Node.js uses: actions/setup-node@v4 with: node-version: "18" registry-url: "https://registry.npmjs.org/" # Uncomment and update with your organization scope: scope: "@your-org"
npm トークンの設定: フォークされたリポジトリの設定で、 NPM_TOKENという名前の GitHub シークレットとして npm トークンを追加します。

カスタマイズしたパッケージの公開

リポジトリをカスタマイズしたら、次の操作を行います。

タグを作成してプッシュする:
# Update version in package.json (optional, the workflow will update it based on the tag) npm version 1.0.0 # Push the tag git push --tags
GitHub Actions は次のようになります:
- パッケージを自動的にビルドする
- タグと一致するようにpackage.jsonのバージョンを更新します
- バンドルされた仕様と設定をnpmに公開する

出版後の使用

カスタマイズされたパッケージのユーザーは、npm を使用してインストールして使用できます。

# Install your customized package
npm install your-custom-mcp-server -g

# Run it
your-custom-mcp-server

構成セクションで説明されているように、環境変数またはコマンドラインオプションを使用してデフォルト設定を上書きできます。

ライセンス

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

OpenAPI to MCP Server

Integrations