swagger-mcp

swagger-mcp

概要

swagger-mcp は、Swagger 2.0 または OpenAPI 3.0 の仕様を読み込み、実行時に MCP ツールを動的に生成するツールです。API エンドポイントごとに 1 つのツールを生成します。これらのツールは、LLM 主導の API 操作において、任意の MCP クライアントで使用できます。

対応する仕様形式：

• Swagger 2.0（swagger: "2.0"）— パス／クエリ／ヘッダーのパラメーターと in: body のリクエストボディ
• OpenAPI 3.0（openapi: "3.0.x"）— パス／クエリ／ヘッダーのパラメーターと、インラインまたは $ref スキーマを使用した requestBody

必須フィールドと任意フィールドは、スキーマの required 配列から読み取られ、生成されるツール定義に反映されます。

📽️ デモ動画

プロジェクトの動作を紹介するデモ動画をご覧ください：

🙌 ご支援のお願い

このプロジェクトに価値を感じていただけましたら、LinkedIn で以下の方法でご支援ください：

• 👍 デモ投稿への「いいね」とシェア
• 💬 コメントでご意見やフィードバックをお寄せください
• 🔗 今後の更新情報を受け取るため、私とつながってください

LinkedIn でのご支援は、より多くの方にプロジェクトを知っていただき、改善を進める助けになります！

前提条件

swagger-mcp を使用するには、以下の依存関係が必要です：

1. LLM モデルの API キー／ローカル LLM：OpenAI、Claude、または Ollama モデルにアクセスできる必要があります。
2. 任意の MCP クライアント：（mark3labs - mcphost を使用）

インストールとセットアップ

go install github.com/danishjsheikh/swagger-mcp@latest

実行設定

Stdio モード（デフォルト）

swagger-mcp --specUrl=https://your_swagger_api_docs.json

SSE モード

swagger-mcp --specUrl=https://your_swagger_api_docs.json --sse --sseAddr=:8080

StreamableHTTP モード

swagger-mcp --specUrl=https://your_swagger_api_docs.json --http --httpAddr=:8080

すべてのフラグ

フラグ	説明
--specUrl	Swagger/OpenAPI JSON 仕様の URL または file:// パス（必須）
--baseUrl	API リクエストのベース URL を上書きします
--sse	stdio の代わりに SSE モードで実行します
--sseAddr	SSE のリッスンアドレス。:Port または IP:Port
--sseUrl	SSE のベース URL（省略した場合は --sseAddr から自動的に導出）
--sseHeaders	SSE から API に転送するリクエストヘッダー（カンマ区切り、例：Authorization,X-Tenant）
--http	stdio の代わりに StreamableHTTP モードで実行します
--httpAddr	StreamableHTTP のリッスンアドレス。:Port または IP:Port
--httpPath	StreamableHTTP エンドポイントのパス（デフォルトは /mcp）
--httpHeaders	HTTP から API に転送するリクエストヘッダー（カンマ区切り）
--includePaths	含めるパスまたは正規表現パターン（カンマ区切り）
--excludePaths	除外するパスまたは正規表現パターン（カンマ区切り）
--includeMethods	含める HTTP メソッド（カンマ区切り、例：GET,POST）
--excludeMethods	除外する HTTP メソッド（カンマ区切り）
--security	認証タイプ：basic、bearer、または apiKey
--basicAuth	user:password 形式の Basic 認証情報
--bearerAuth	Authorization ヘッダーに設定する Bearer トークン
--apiKeyAuth	API キー：passAs:name=value — passAs は header、query、または cookie。複数指定する場合はカンマで区切ります（例：header:token=abc,query:user=foo）
--headers	すべてのリクエストに設定する追加の静的ヘッダー。name1=value1,name2=value2

Xquik OpenAPI の例

Xquik は、X/Twitter 自動化 API 用の OpenAPI ドキュメントをリモートで公開しています。 API キーヘッダーを使用するため、--security=apiKey と --apiKeyAuth を指定してキーを渡します：

export XQUIK_API_KEY="your-xquik-api-key"

swagger-mcp \
  --specUrl=https://xquik.com/openapi.json \
  --baseUrl=https://xquik.com \
  --security=apiKey \
  --apiKeyAuth=header:x-api-key=$XQUIK_API_KEY

同じ引数を MCP クライアントの設定でも使用できます：

{
  "mcpServers": {
    "xquik": {
      "command": "swagger-mcp",
      "args": [
        "--specUrl=https://xquik.com/openapi.json",
        "--baseUrl=https://xquik.com",
        "--security=apiKey",
        "--apiKeyAuth=header:x-api-key=<XQUIK_API_KEY>"
      ]
    }
  }
}

MCP の設定

mcphost と統合するには、.mcp.json に以下の設定を追加します：

{
    "mcpServers": {
        "swagger_loader": {
            "command": "swagger-mcp",
            "args": ["--specUrl=<swagger/doc.json_url>"]
        }
    }
}

Bearer 認証とパスフィルタリングを使用する場合：

{
    "mcpServers": {
        "swagger_loader": {
            "command": "swagger-mcp",
            "args": [
                "--specUrl=https://api.example.com/openapi.json",
                "--security=bearer",
                "--bearerAuth=your-token-here",
                "--includeMethods=GET,POST"
            ]
        }
    }
}

リクエストボディのサポート

Swagger 2.0 と OpenAPI 3.0 の両方のリクエストボディをサポートしています。

• Swagger 2.0：parameters の in: body と、definitions 内の $ref またはインラインスキーマ
• OpenAPI 3.0：requestBody.content.<media-type>.schema。$ref の場合は components/schemas から解決し、オブジェクトスキーマの場合はインラインで使用します。

スキーマの required 配列に記載されたフィールドは、MCP ツールで必須として扱われます。それ以外のフィールドはすべて任意で、指定されていない場合はリクエストから省略されます。

デモの流れ

1. バックエンドの例：

   go install github.com/danishjsheikh/go-backend-demo@latest 
   go-backend-demo
   

2. Ollama

   ollama run llama3.2
   

3. MCP クライアント

   go install github.com/mark3labs/mcphost@latest
   mcphost -m ollama:llama3.2 --config <.mcp.json_file_path>
   

フロー図

🛠️ お困りですか

現在、以下の点を強化するために、ツール定義の改善に取り組んでいます。
✅ より正確な応答を実現するためのエラーハンドリングの改善
✅ LLM の動作制御により、独自の記憶を使わず、API の応答のみを参照するようにすること
✅ API からの厳密なデータ取得を徹底し、ハルシネーションやランダムなデータ生成を防止すること

これらの改善に関する知見や提案がありましたら、ぜひ以下の方法で貢献してください。

• 同様の実装における経験の共有
• ツール定義の変更案の提案
• 現在の制限事項に関するフィードバック

皆さまからのご意見は、このツールの信頼性と有用性を高めるうえで非常に貴重です！ 🚀