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",
"@tyk-technologies/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",
"@tyk-technologies/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",
"@tyk-technologies/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', '@tyk-technologies/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
@tyk-technologies/api-to-mcp --spec=./path/to/openapi.json
# Apply overlays to the spec
@tyk-technologies/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)
@tyk-technologies/api-to-mcp --spec=./path/to/openapi.json --whitelist="getPet*,POST:/users/*"
# Specify target API URL
@tyk-technologies/api-to-mcp --spec=./path/to/openapi.json --targetUrl=https://api.example.com
# Add custom headers to all API requests
@tyk-technologies/api-to-mcp --spec=./path/to/openapi.json --headers='{"X-Api-Version":"1.0.0"}'
# Disable the X-MCP header
@tyk-technologies/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
構成セクションで説明されているように、環境変数またはコマンドライン オプションを使用してデフォルト設定を上書きできます。
ライセンス
マサチューセッツ工科大学