@openapi-mcp/server

@openapi-mcp/server

openapi-mcp-server は、Model Context Protocol（MCP）を使用して、OpenAPI 仕様と AI アシスタントをつなぐ強力なブリッジです。あらゆる OpenAPI／Swagger API 仕様を、Claude Desktop などの AI アシスタントが使用できる MCP ツールに自動変換します。これにより、AI アシスタントはカスタム連携を必要とせず、サービスを通じて実際の操作を実行できるようになり、API とシームレスにやり取りできます。

機能

⚠️ 注意： このサーバーでは、OpenAPI／Swagger 仕様内のすべてのオペレーションに operationId が必須です。operationId がないオペレーションがあると、サーバーは起動または仕様の処理に失敗します。すべてのオペレーションに、一意で内容がわかる operationId が明示的に割り当てられていることを必ず確認してください。

• 🔌 OpenAPI 連携
  • OpenAPI／Swagger 仕様を MCP ツールに自動変換
• 📚 複数の OpenAPI バージョン
  • OpenAPI v3.0.0 および v3.1.0 をサポート
• 🔐 認証のサポート：
  • HTTP 認証スキーム：
    • Basic 認証
    • Bearer トークン認証（静的トークン。例：Personal Access Token）
    • RFC 7235 で定義されているその他の HTTP スキーム
  • API キー：
    • ヘッダーベースの API キー

制限事項

⚠️ バージョンのサポート：

• OpenAPI v2.0（Swagger）は現在サポートされていません

⚠️ 認証の制限事項：

• OAuth 2.0 認証はサポートされていません
• OpenID Connect Discovery はサポートされていません
• クエリパラメーターを使用した API キーはサポートされていません
• Cookie ベースの認証はサポートされていません
• 動的 JWT 認証（ログイン時に生成されるトークン）はサポートされていません

インストール

# Clone the repository
git clone https://github.com/sotayamashita/openapi-mcp-server.git
cd openapi-mcp-server

# Install dependencies
bun install

使用方法

OpenAPI 仕様の URL またはファイルパスを指定して、サーバーを実行できます。

# Using a local file
bun run src/index.ts ./path/to/openapi.yml

# Using a URL
bun run src/index.ts --api https://example.com/api-spec.json

設定

環境変数

• BASE_URL

  • 必須：はい
  • 説明：API エンドポイント。Server Object の URL

• HEADERS

  • 必須：いいえ
  • デフォルト：{"Content-Type": "application/json","User-Agent": "openapi-mcp-server"}
  • 説明：デフォルトのヘッダーを上書きするカスタムヘッダー

Claude Desktop との連携

この MCP サーバーを Claude Desktop で使用するには：

1. Claude Desktop の設定ファイルを開きます。

   # macOS/Linux
   code ~/Library/Application\ Support/Claude/claude_desktop_config.json
   

2. 次の設定を追加します。

   {
     "mcpServer": {
       "openapi-mcp-server": {
         "command": "bun",
         "args": [
           "/path/to/openapi-mcp-server/src/index.ts",
           "/path/to/openapi-mcp-server/demo/openapi.yml"
         ],
         "env": {
           "BASE_URL": "https://api.example.com/v1/",
           "HEADERS": "{\"Authorization\": \"Bearer ****\"}"
         }
       }
     }
   }
   

詳しい手順については、MCP クイックスタートガイドを参照してください。

Cursor との連携

この MCP サーバーを Cursor のグローバル設定として使用するには：

1. Cursor を開きます
2. Cursor の「Settings」>「MCP」を開きます
3. 「+ Add new global MCP Server」をクリックします
4. 次の設定を追加します。

   {
     "mcpServer": {
       "openapi-mcp-server": {
         "command": "bun",
         "args": [
           "/path/to/openapi-mcp-server/src/index.ts",
           "/path/to/openapi-mcp-server/demo/openapi.yml"
         ],
         "env": {
           "BASE_URL": "https://api.example.com/v1/",
           "HEADERS": "{\"Authorization\": \"Bearer ****\"}"
         }
       }
     }
   }
   

詳しい手順については、Cursor の Model Context Protocolを参照してください。

ベストプラクティス

OpenAPI／Swagger 仕様

説明的な operationId フィールドを使用する

OpenAPI/Swagger 仕様の operationId フィールドは、AI アシスタントにツールをどのように提示するかにおいて重要な役割を果たします。API を MCP ツールに変換する際は、次の点に注意してください。

• ツールの命名：operationId は MCP ツール名としてそのまま使用されます
• 明確さ：説明的な operationId の値を指定すると、AI アシスタントが API を理解し、使いやすくなります
• 一貫性：一貫した命名パターンを使用してください（例：getUser、createUser、updateUserPassword）

適切に定義された操作の例：

paths:
  /users/{userId}:
    get:
      operationId: getUserById
      summary: Retrieve user information
      description: Returns detailed information about a specific user

詳細な操作の説明を記述する

各操作の description フィールドも同様に重要です。

• ツールの選択：AI アシスタントはこの説明を使って、特定のタスクに適したツールを判断します
• 理解：包括的な説明は、AI が操作の内容を正確に理解するのに役立ちます
• コンテキスト：パラメーター、期待されるレスポンス、発生する可能性のあるエラーに関する情報を含めてください

適切に説明された操作の例：

paths:
  /users:
    post:
      operationId: createUser
      summary: Create a new user account
      description: |
        Creates a new user in the system. Requires a unique email address and a 
        password that meets security requirements (min 8 chars, including uppercase, 
        lowercase, number). Returns the created user object with an assigned user ID.

十分な説明がないと、AI アシスタントはユーザーのリクエストに適した操作を特定できなかったり、誤って使用したりする可能性があります。API の説明の品質は、AI がツールをどれだけ効果的に活用できるかに直接影響します。

開発

開発コマンド

# Run tests
bun vitest run

# Run tests with watch mode
bun vitest

# Run tests with coverage
bun vitest run --coverage

# Format code
bun prettier . --write

手動リリースプロセス（リリースブランチを使用）

このセクションでは、専用のリリースブランチを使用して新しいリリースを作成する手動の手順を説明します。この方法を使うと、公開するまでリリースプロセスを main ブランチから切り離せます。

前提条件：

• リリースに含めるすべての変更が main ブランチにマージされていること。
• npm アカウントにログインしていること（npm login）。
• Changesets CLI を利用できること（このガイドでは bunx を使用します）。

手順：

1. main が最新であることを確認します：

   git checkout main
   git pull origin main
   

2. リリースブランチを作成します： リリースするバージョンに合わせて名前を付けます（例：v0.1.0）。

   git checkout -b release/vX.Y.Z main
   

   vX.Y.Z を対象のバージョンに置き換えます。

3. バージョンを更新し、変更履歴を更新します： このコマンドは変更セットファイル（.changeset/ 内）を使用し、package.json のバージョンと CHANGELOG.md を更新します。

   bunx @changesets/cli version
   

   package.json と CHANGELOG.md に適用された変更を確認し、正しいことを確かめます。

4. バージョン変更をコミットします：

   git add .
   git commit -m "chore: update versions and changelogs for vX.Y.Z"
   

   vX.Y.Z を対象のバージョンに置き換えます。

5. プロジェクトをビルドします： 最新の変更を含む配布ファイルが生成されていることを確認します。

   bun run build
   

6. npm に公開します： 新しいバージョンを npm レジストリに公開します。

   npm publish
   

   スコープ付きのパブリックパッケージでは、package.json に "publishConfig": { "access": "public" } が含まれていることを確認してください。 (代わりに bun publish を使用することもできますが、使用する場合は、スコープ付きのパブリックパッケージでの動作を確認してください。)

7. Git でリリースにタグを付けます： npm に公開したバージョンと一致する Git タグを作成します。

   # X.Y.Z を実際のバージョン番号（例：0.1.0）に置き換えます
   git tag @openapi-mcp/[email protected]
   

8. リリースブランチを main にマージします： これにより、バージョン変更と CHANGELOG の更新が main ブランチに反映されます。

   git checkout main
   git merge --no-ff release/vX.Y.Z
   

   （--no-ff を使用するとマージコミットが作成され、Git の履歴でリリースを追跡しやすくなります。）

9. main と新しいタグをリモートリポジトリにプッシュします：

   git push origin main --tags
   

10. （任意）クリーンアップ： 不要になった場合は、リリースブランチをローカルとリモートから削除します。

    git branch -d release/vX.Y.Z
    git push origin --delete release/vX.Y.Z
    

Changesets の使用方法について詳しくは、Changesets の公式ドキュメントを参照してください。