swagger-mcp

swagger-mcp

Overview

swagger-mcp is a tool that reads a Swagger 2.0 or OpenAPI 3.0 specification and dynamically generates MCP tools at runtime — one tool per API endpoint. These tools can be used by any MCP client for LLM-driven API interaction.

Supported spec formats:

• Swagger 2.0 (swagger: "2.0") — path/query/header parameters and in: body request bodies
• OpenAPI 3.0 (openapi: "3.0.x") — path/query/header parameters and requestBody with inline or $ref schemas

Required and optional fields are read from the schema's required array and honoured in the generated tool definitions.

📽️ Demo Video

Check out demo video showcasing the project in action:

🙌 Support

If you find this project valuable, please support me on LinkedIn by:

• 👍 Liking and sharing our demo post
• 💬 Leaving your thoughts and feedback in the comments
• 🔗 Connecting with me for future updates

Your support on LinkedIn will help me reach more people and improve the project!

Prerequisites

To use swagger-mcp, ensure you have the following dependencies:

1. LLM Model API Key / Local LLM: Requires access to OpenAI, Claude, or Ollama models.
2. Any MCP Client: (Used mark3labs - mcphost)

Installation and Setup

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

Run Configuration

Stdio mode (default)

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

SSE mode

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

StreamableHTTP mode

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

All flags

Flag	Description
--specUrl	URL or file:// path of the Swagger/OpenAPI JSON spec (required)
--baseUrl	Override the base URL for API requests
--sse	Run in SSE mode instead of stdio
--sseAddr	SSE listen address, :Port or IP:Port
--sseUrl	SSE base URL (auto-derived from --sseAddr if omitted)
--sseHeaders	Comma-separated request headers to forward from SSE to API (e.g. Authorization,X-Tenant)
--http	Run in StreamableHTTP mode instead of stdio
--httpAddr	StreamableHTTP listen address, :Port or IP:Port
--httpPath	StreamableHTTP endpoint path (default /mcp)
--httpHeaders	Comma-separated request headers to forward from HTTP to API
--includePaths	Comma-separated paths or regex patterns to include
--excludePaths	Comma-separated paths or regex patterns to exclude
--includeMethods	Comma-separated HTTP methods to include (e.g. GET,POST)
--excludeMethods	Comma-separated HTTP methods to exclude
--security	Auth type: basic, bearer, or apiKey
--basicAuth	Basic auth credentials in user:password format
--bearerAuth	Bearer token for the Authorization header
--apiKeyAuth	API key(s): passAs:name=value — passAs is header, query, or cookie; multiple entries comma-separated (e.g. header:token=abc,query:user=foo)
--headers	Additional static headers for every request, name1=value1,name2=value2

Xquik OpenAPI Example

Xquik publishes a remote OpenAPI document for its X/Twitter automation API. Because it uses an API key header, pass the key with --security=apiKey and --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

The same arguments can be used in an MCP client config:

{
  "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 Configuration

To integrate with mcphost, include the following configuration in .mcp.json:

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

With bearer auth and path filtering:

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

Request Body Support

Both Swagger 2.0 and OpenAPI 3.0 request bodies are supported:

• Swagger 2.0: parameters with in: body and a $ref or inline schema under definitions
• OpenAPI 3.0: requestBody.content.<media-type>.schema — resolved from components/schemas if a $ref, or used inline if an object schema

Fields listed in the schema's required array are marked as required in the MCP tool. All other fields are optional and are omitted from the request if not provided.

Demo Flow

1. Some Backend:

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

2. Ollama

   ollama run llama3.2
   

3. MCP Client

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

Flow Diagram

🛠️ Need Help

I am working on improving tool definitions to enhance:
✅ Better error handling for more accurate responses
✅ LLM behavior control to ensure it relies only on API responses and does not use its own memory
✅ Preventing hallucinations and random data generation by enforcing strict data retrieval from APIs

If you have insights or suggestions on improving these aspects, please contribute by:

• Sharing your experience with similar implementations
• Suggesting modifications to tool definitions
• Providing feedback on current limitations

Your input will be invaluable in making this tool more reliable and effective! 🚀