openapi

mcp-openapi

あらゆる OpenAPI／Swagger 仕様を MCP ツールに変換し、Claude などの AI アシスタントから REST API を呼び出せるようにします。

mcp-openapi に OpenAPI 3.x または Swagger 2.0 の仕様 URL を指定すると、Model Context Protocol (MCP) ツールが自動的に生成されます。コード生成も、設定ファイルも、定型コードも不要です。AI アシスタントは、数秒であらゆる API エンドポイントを呼び出せるツールとして利用できます。

---

クイックスタート

1. 実行する（インストール不要）：

npx mcp-openapi --spec https://petstore3.swagger.io/api/v3/openapi.json

2. Claude Desktop に追加する（claude_desktop_config.json）：

{
  "mcpServers": {
    "petstore": {
      "command": "npx",
      "args": [
        "mcp-openapi",
        "--spec", "https://petstore3.swagger.io/api/v3/openapi.json"
      ]
    }
  }
}

3. Claude に使うよう依頼する：

「ストアで利用できるペットをすべて一覧表示して」

Claude は find_pets_by_status、get_pet_by_id、add_pet などの MCP ツールを認識し、直接呼び出します。

---

mcp-openapi を選ぶ理由

多くの MCP と API のブリッジでは、ツール定義を手作業で記述するか、仕様からコードを生成する必要があります。mcp-openapi なら、こうした作業は不要です。

機能	mcp-openapi	手書きの MCP サーバー	汎用 HTTP ツール
設定不要でセットアップ	はい	いいえ	一部
OpenAPI 3.x + Swagger 2.0	はい	該当なし	該当なし
フラットなパラメータスキーマ（LLM に最適化）	はい	手動	いいえ
operationId に基づくスマートなツール名	はい	手動	いいえ
認証（API キー、Bearer、OAuth2）	組み込み	自分で実装	自分で実装
指数バックオフによる再試行	組み込み	自分で実装	自分で実装
LLM コンテキストに合わせたレスポンスの切り詰め	組み込み	自分で実装	いいえ

フラットなパラメータスキーマが、このツールの大きな差別化要因です。ネストされた JSON オブジェクトを渡す代わりに（LLM はこれを頻繁に誤ります）、mcp-openapi はパス、クエリ、ヘッダー、本文のパラメータを単一のフラットなオブジェクトにまとめます。これにより、ツール呼び出しの精度が大幅に向上します。

---

仕組み

OpenAPI/Swagger Spec          mcp-openapi               AI Assistant
     (URL or file)                                      (Claude, etc.)
          |                         |                         |
          |   1. Parse & validate   |                         |
          |------------------------>|                         |
          |                         |                         |
          |   2. Generate MCP tools |                         |
          |   (one per endpoint)    |                         |
          |------------------------>|                         |
          |                         |                         |
          |                         |   3. Register tools     |
          |                         |   via stdio transport   |
          |                         |------------------------>|
          |                         |                         |
          |                         |   4. AI calls a tool    |
          |                         |<------------------------|
          |                         |                         |
          |   5. Build & execute    |                         |
          |   HTTP request          |                         |
          |<------------------------|                         |
          |                         |                         |
          |   6. Return truncated   |                         |
          |   response to AI        |                         |
          |------------------------>|------------------------>|

各 API エンドポイントは 1 つの MCP ツールになります。

• ツール名は operationId（snake_case に変換）から導出されるか、method + path から生成されます。
• パラメータは単一の入力スキーマにフラット化されます（パス、クエリ、ヘッダー、本文のパラメータを統合）。
• レスポンスは LLM のコンテキスト制限内に収まるよう、約 50KB で切り詰められます。
• エラー（429、5xx）が発生すると、指数バックオフによる自動再試行が行われます（最大 3 回）。

---

Claude Desktop との連携

設定ファイルを編集して、任意の API を Claude Desktop に追加できます。

場所：

• macOS：~/Library/Application Support/Claude/claude_desktop_config.json
• Windows：%APPDATA%\Claude\claude_desktop_config.json

パブリック API（認証なし）

{
  "mcpServers": {
    "petstore": {
      "command": "npx",
      "args": [
        "mcp-openapi",
        "--spec", "https://petstore3.swagger.io/api/v3/openapi.json"
      ]
    }
  }
}

Bearer トークンを使う API

{
  "mcpServers": {
    "github": {
      "command": "npx",
      "args": [
        "mcp-openapi",
        "--spec", "https://raw.githubusercontent.com/github/rest-api-description/main/descriptions/api.github.com/api.github.com.json",
        "--auth-type", "bearer",
        "--auth-token", "$GITHUB_TOKEN",
        "--prefix", "github",
        "--include", "listReposForAuthenticatedUser,getRepo,listIssues,createIssue"
      ],
      "env": {
        "GITHUB_TOKEN": "ghp_your_token_here"
      }
    }
  }
}

API キーを使う API

{
  "mcpServers": {
    "weather": {
      "command": "npx",
      "args": [
        "mcp-openapi",
        "--spec", "https://api.weather.example.com/openapi.json",
        "--auth-type", "api-key",
        "--auth-name", "X-API-Key",
        "--auth-value", "$WEATHER_API_KEY",
        "--auth-in", "header"
      ],
      "env": {
        "WEATHER_API_KEY": "your_key_here"
      }
    }
  }
}

---

CLI リファレンス

npx mcp-openapi --spec <url-or-path> [options]

一般オプション

オプション	短縮形	デフォルト	説明
--spec <url|path>	-s	必須	OpenAPI 仕様の URL またはローカルファイルのパス
--config <path>	-c		JSON 設定ファイルのパス
--base-url <url>		仕様から取得	API のベース URL を上書きします
--prefix <name>			すべてのツール名に付けるプレフィックス（例：github → github_list_repos）
--include <patterns>		すべて	含める operationId をカンマ区切りで指定します
--exclude <patterns>		なし	除外する operationId をカンマ区切りで指定します
--timeout <ms>		30000	HTTP リクエストのタイムアウト（ミリ秒）
--max-retries <n>		3	429／5xx レスポンス時の最大再試行回数
--header <name:value>	-H		カスタムヘッダー（複数回指定可能）
--transport <type>		stdio	トランスポートの種類：stdio または sse
--port <n>		3000	SSE トランスポートのポート
--help	-h		ヘルプを表示します
--version	-v		バージョンを表示します
--license-key <key>			Pro ライセンスキー（または $MCP_OPENAPI_LICENSE_KEY 環境変数）
--server <selector>		0	インデックス、一部一致する URL、または完全一致する URLで API サーバーを選択します
--no-doc-warnings			起動時のドキュメント品質に関する警告を抑制します
--dynamic-discovery		自動（100 以上）	大規模な API で動的なツール検出を有効にします

認証オプション

Bearer トークン：

オプション	説明
--auth-type bearer	Bearer トークン認証を使用します
--auth-token <token>	トークンの値（$ENV_VAR 形式に対応）

API キー：

オプション	説明
--auth-type api-key	API キー認証を使用します
--auth-name <name>	ヘッダーまたはクエリパラメーターの名前
--auth-value <value>	API キーの値（$ENV_VAR 形式に対応）
--auth-in <header|query>	キーの送信先（デフォルト：header）

OAuth2 クライアントクレデンシャル：

オプション	説明
--auth-type oauth2	OAuth2 クライアントクレデンシャルフローを使用します
--auth-client-id <id>	OAuth2 クライアント ID
--auth-client-secret <secret>	OAuth2 クライアントシークレット
--auth-token-url <url>	トークンエンドポイントの URL
--auth-scopes <scopes>	スコープをカンマ区切りで指定します

---

CLI の使用例

# Basic usage with a remote spec
npx mcp-openapi --spec https://petstore3.swagger.io/api/v3/openapi.json

# Local YAML spec with Bearer auth
npx mcp-openapi --spec ./api.yaml --auth-type bearer --auth-token '$API_KEY'

# Filter to specific endpoints with a prefix
npx mcp-openapi --spec ./api.json --prefix myapi --include 'listUsers,getUser'

# Override base URL (useful for local dev)
npx mcp-openapi --spec https://api.example.com/openapi.json --base-url http://localhost:3000

# Add custom headers
npx mcp-openapi --spec ./api.json -H 'X-Custom: value' -H 'X-Another: value2'

# Use a JSON config file
npx mcp-openapi --config ./mcp-config.json

# Select staging server
npx mcp-openapi --spec ./api.json --server staging

# Large API with dynamic discovery
npx mcp-openapi --spec https://api.stripe.com/openapi.json --dynamic-discovery

設定ファイルの形式

CLI フラグの代わりに、JSON 設定ファイルを使用できます：

{
  "spec": "https://api.example.com/openapi.json",
  "prefix": "myapi",
  "include": ["listUsers", "getUser", "createUser"],
  "auth": {
    "type": "bearer",
    "token": "$API_TOKEN"
  },
  "timeout": 15000,
  "maxRetries": 2,
  "headers": {
    "X-Custom-Header": "value"
  }
}

CLI 引数は設定ファイルの値より優先されます。

---

対応する仕様

形式	バージョン	ファイルの種類
OpenAPI	3.0.x, 3.1.x	.json、.yaml、.yml
Swagger	2.0	.json、.yaml、.yml

仕様は次の場所から読み込めます：

• リモート URL（https://...）
• ローカルファイルのパス（./api.yaml、/absolute/path/spec.json）

---

v0.3.0 の機能

ドキュメント品質に関する警告

起動時に、mcp-openapi は各ツールのドキュメント品質を確認します。エンドポイントの説明が簡潔すぎる（50 文字未満）場合、警告が表示されます：

[mcp-openapi] WARN: Doc quality: 11 of 47 tools have sparse documentation (<50 chars)
[mcp-openapi] WARN:   Affected: getUser, createOrder, deleteItem, updateCart, listTags, ...
[mcp-openapi] WARN:   LLM accuracy may be reduced for these endpoints.

これにより、LLM のツール呼び出し精度を低下させる可能性のある API エンドポイントを特定できます。--no-doc-warnings で警告を抑制できます。

サーバーのフィルタリング

OpenAPI 仕様では、複数のサーバー（本番、ステージング、開発）を定義できます。使用するサーバーを選択します：

# Use first server (default behavior)
mcp-openapi --spec api.json --server 0

# Match by URL keyword
mcp-openapi --spec api.json --server prod

# Exact URL
mcp-openapi --spec api.json --server https://api.example.com/v2

セレクターが一致しない場合は、利用可能なすべてのサーバーが一覧表示されます。

動的なツール検出

100 個以上のエンドポイントを持つ大規模な API では、すべてのツールを一度に登録すると、LLM のコンテキストを圧迫することがあります。動的な検出では、代わりに 3 つのメタツールを登録します：

メタツール	説明
search_operations(query)	名前、説明、タグのキーワードでツールを検索します
list_by_tag(tag?)	OpenAPI のタグでツールを参照するか、すべてのタグを一覧表示します
get_tool_details(tool_name)	特定のツールのパラメーター・スキーマ全体を取得します

LLM はこれらのメタツールを使って API を調べてから、名前を指定して特定のエンドポイントを呼び出します。

# Explicit opt-in
mcp-openapi --spec large-api.json --dynamic-discovery

# Auto-enabled when spec has 100+ endpoints
mcp-openapi --spec https://api.github.com/openapi.json

または設定ファイルで指定します：

{
  "spec": "https://api.stripe.com/openapi.json",
  "dynamicDiscovery": true,
  "auth": { "type": "bearer", "token": "$STRIPE_KEY" }
}

---

Pro 機能（v0.2.0 以降）

mcp-openapi には、チームやパワーユーザー向けのオプションの Pro 機能が含まれており、ライセンスキーで有効化します。

カスタムレスポンス変換

JMESPath の式を使って、API レスポンスが LLM に届く前に整形できます。トークン使用量を削減し、精度を高めます。

{
  "spec": "https://api.github.com/openapi.json",
  "licenseKey": "$MCP_OPENAPI_LICENSE_KEY",
  "transforms": {
    "list_repos": "data[].{name: name, stars: stargazers_count, url: html_url}",
    "list_*": "data[].{id: id, name: name}"
  }
}

スマートなレスポンス処理

大きなレスポンスを 50KB で一律に切り詰める代わりに、Pro ではインテリジェントな切り詰めが可能です。

• 配列のスライス：大きな配列では、最初の N 件とメタデータ（"showing 10 of 847 items"）を表示します
• 深さのプルーニング：深くネストされたオブジェクトは、設定可能な深さを超えると要約されます
• 構造の保持：JSON の途中で切断されることなく、データの構造を常に確認できます

{
  "spec": "./api.json",
  "licenseKey": "$MCP_OPENAPI_LICENSE_KEY",
  "response": {
    "maxLength": 50000,
    "arraySliceSize": 10,
    "maxDepth": 4
  }
}

近日公開

• 複数 API の合成 — 複数の OpenAPI 仕様を 1 つの MCP セッションに読み込みます
• 使用状況の分析 — ツール呼び出し、レイテンシ、エラー率を追跡します

Pro に興味がありますか？リポジトリにスターを付け、issue を作成して早期アクセスをお申し込みください。

---

プログラムからの使用

mcp-openapi は、ご自身の MCP サーバーでライブラリとして使用することもできます。

import { createServer } from 'mcp-openapi';

const { server, tools, spec } = await createServer({
  spec: 'https://petstore3.swagger.io/api/v3/openapi.json',
  prefix: 'petstore',
  auth: {
    type: 'bearer',
    token: process.env.API_TOKEN,
  },
});

console.log(`Loaded ${tools.length} tools from ${spec.info.title}`);

---

要件

• Node.js 18 以降
• OpenAPI 3.x または Swagger 2.0 の仕様（URL またはローカルファイル）

---

コントリビューション

コントリビューションを歓迎します。始める手順は以下のとおりです。

git clone https://github.com/Docat0209/mcp-openapi.git
cd mcp-openapi
pnpm install
pnpm test
pnpm build

PR を提出する前に：

1. 新機能のテストを追加します
2. pnpm lint を実行し、問題があれば修正します
3. コミットメッセージには Conventional Commits に従います

---

関連項目

• graphql-to-mcp — GraphQL API 向けの同じゼロ設定アプローチ

ライセンス

MIT

---

キーワード

mcp, model-context-protocol, openapi, swagger, claude, ai, llm, api, tools, rest-api, ai-tools, mcp-server