openapi-mcp

OpenAPI MCP

任意の OpenAPI 3 仕様を、動作する MCP サーバーに変換します。ファイルは 1 つ、約 130 行で、依存関係はありません。

node openapi-mcp.mjs https://your-api.com/openapi.json

すべての API エンドポイントが、AI クライアント（Claude、Cursor など）から呼び出せるツールになります。コード生成も、エンドポイントごとのファイルもありません。起動時に仕様を読み込み、ツールをメモリ上に構築します。

クイックスタート

Node 18 以降が必要です。

git clone <this-repo>
cd openapi-mcp
node openapi-mcp.mjs sample/animechan.openapi.json

openapi-mcp: 4 tools from "Animechan" -> ... と出力された後、MCP クライアントを待機します。これは正常な動作です。stdin/stdout 経由で JSON-RPC をやり取りするため、人が読むことを想定していません。

AI クライアントで使用する

Claude Desktop（ローカルモード）

これを ~/Library/Application Support/Claude/claude_desktop_config.json に追加し、アプリを再起動します。

{
  "mcpServers": {
    "animechan": {
      "command": "node",
      "args": ["/full/path/openapi-mcp.mjs", "/full/path/animechan.openapi.json"]
    }
  }
}

クライアントが node を見つけられない場合は、which node で確認したフルパスを使用してください。

Claude Code（リモートモード）

サーバーを起動し、登録します。

MCP_AUTH_TOKEN=secret node openapi-mcp.mjs sample/animechan.openapi.json --http 8787

claude mcp add --transport http animechan http://localhost:8787/mcp \
  --header "Authorization: Bearer secret"

その後、「Narutoからランダムな名言を取得して」と自然な英語で尋ねます。

2 つのモード

モード	コマンド	用途
ローカル（stdio）	node openapi-mcp.mjs <spec>	クライアントが自分のマシン上でサーバーを起動する場合
リモート（HTTP）	node openapi-mcp.mjs <spec> --http <port>	クライアントが URL に接続する場合、またはセルフホストする場合

HTTP モードでは、クライアントは POST http://host:<port>/mcp として JSON-RPC メッセージを送信します。--http <port> は最後に指定してください。

手動でテストします。

curl -X POST localhost:8787/mcp -H 'Authorization: Bearer secret' \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/list"}'

オプション

node openapi-mcp.mjs <spec-url-or-file> [base-url] [--http <port>]

引数 / 環境変数	説明
<spec-url-or-file>	URL またはローカルファイル（JSON）として指定する OpenAPI 3 仕様（YAML には npm i yaml が必要です）
[base-url]	API アドレスを上書きします。デフォルトは仕様の servers[0].url です
API_TOKEN	API 用のシークレットです。仕様の securitySchemes によって設定場所が決まります（認証を参照）
OAUTH_CLIENT_ID、OAUTH_CLIENT_SECRET	OAuth2 クライアントクレデンシャル：トークンは自動的に取得・更新されます
OAUTH_REFRESH_TOKEN	OAuth2 リフレッシュトークングラント（クライアント ID とシークレットと併用します）
OAUTH_TOKEN_URL、OAUTH_SCOPE	オプション：仕様の tokenUrl を上書きするか、スコープをリクエストします
API_HEADERS	スキームでカバーされない項目に使用する、すべての呼び出しで送信される追加ヘッダーです。例：'{"X-App-Id":"abc"}'
TOOL_FILTER	正規表現です。名前が一致するツールのみ公開します。例：読み取り専用の場合は '^(get|list)'
MCP_AUTH_TOKEN	HTTP モードのみ。すべてのリクエストに Authorization: Bearer <token> が必要です

大規模な API には、数百ものエンドポイントがある場合があります。ツールが多すぎるとモデルの選択精度が下がるため、TOOL_FILTER を使って必要なものに絞り込んでください。

認証

サーバーは仕様から securitySchemes を読み取り、シークレットを適切な場所に設定します。シークレットは環境変数として指定するだけです。

仕様の記述	設定する値	送信される内容
http / bearer	API_TOKEN=tok	Authorization: Bearer tok
http / basic	API_TOKEN=user:pass	Authorization: Basic <base64>
ヘッダーの apiKey	API_TOKEN=key	仕様で指定された名前のヘッダー（例：X-Key: key）
クエリの apiKey	API_TOKEN=key	仕様で指定された名前のクエリパラメーター
Cookie の apiKey	API_TOKEN=key	Cookie: name=key
oauth2 / openIdConnect、アクセストークンをすでにお持ちの場合	API_TOKEN=token	Authorization: Bearer token
oauth2、マシン間認証の場合	OAUTH_CLIENT_ID + OAUTH_CLIENT_SECRET	tokenUrl から取得したトークンをキャッシュし、有効期限前に更新
oauth2、別の場所ですでに一度ログインした場合	上記の2つ + OAUTH_REFRESH_TOKEN	リフレッシュトークンを使ってアクセストークンを更新

Claude Desktop の例：

{
  "mcpServers": {
    "my-api": {
      "command": "node",
      "args": ["/full/path/openapi-mcp.mjs", "https://my-api.com/openapi.json"],
      "env": { "API_TOKEN": "your-secret" }
    }
  }
}

注意：

• 仕様でセキュリティスキームが宣言されているのに認証情報が設定されていない場合、起動時に警告が stderr に出力されます。
• 仕様に複数のスキームが記載されている場合は、最上位の security リストにある最初のスキーム（または最初に定義されたスキーム）が使われます。エンドポイントごとの security のオーバーライドは適用されないため、シークレットはすべての呼び出しで送信されます。
• OAuth クライアント認証情報は、トークンエンドポイントに HTTP Basic 認証で送信されます。
• OAuth のブラウザーログイン（認可コードフロー）は組み込まれていません。プロバイダーのツールを使ってトークンまたはリフレッシュトークンを一度取得し、それを渡してください。
• プロバイダーがリフレッシュトークンをローテーションする場合、新しいトークンはメモリ内にのみ保持されるため、再起動すると失われます。

仕組み

1. 読み込み： 仕様を読み込み、$ref ポインターを解決します。
2. ツールの構築： 各オペレーションが1つの MCP ツールになります。operationId が名前、summary が説明となり、パラメーターとリクエストボディが入力スキーマになります。
3. 呼び出し： ツールを呼び出すと実際の HTTP リクエストが行われ、HTTP <status> に続いてレスポンスボディが返されます（50,000文字で切り詰められます）。
4. 提供： ツールは stdio または HTTP 経由で JSON-RPC 2.0 を使って提供されます。

OpenAPI 仕様のない API

小規模な公開 API の多くは HTML のドキュメントしかありません。その場合は、小さな仕様を手作業で作成し（sample/animechan.openapi.json を参照。約35行で4つのツールを定義）、同じ方法で実行してください。

制限事項

• OpenAPI 3 のみ対応しています。Swagger 2.0 の仕様は先に変換してください。
• JSON リクエストボディのみ対応しています。ファイルのアップロードには対応していません。
• 認証：Bearer、Basic、API キー、OAuth2 のクライアント認証情報またはリフレッシュトークンに対応しています。対話型の OAuth ログインには対応しておらず、API ごとに使用できるスキームは1つです。
• HTTP モードはプレーンな HTTP を使用します（デプロイ時は HTTPS を前段に配置してください）。ストリーミング、バッチリクエスト、サーバーに接続するクライアント向けの OAuth には対応していません（MCP_AUTH_TOKEN の Bearer トークンのみ対応しています）。一部のリモートクライアントでは、これらが必要になる場合があります。
• HTTP モードはプレーンな HTTP を使用します（デプロイ時は HTTPS を前段に配置してください）。ストリーミング、バッチリクエスト、OAuth には対応していません。一部のリモートクライアントでは、これらが必要になる場合があります。
• リモートにデプロイすると、すべてのユーザーがサーバーの IP を共有するため、上流のレート制限は全ユーザーに適用されます。MCP_AUTH_TOKEN を設定してください。設定しない場合、URL を見つけた人は誰でも API キーを使用できます。

コントリビューション

Issue やプルリクエストを歓迎します。小さく読みやすい状態を保つことを目指しているため、新機能はそれぞれ数行程度に抑えてください。