mcp-swagger

The mcp-swagger server exposes Swagger/OpenAPI documentation to AI models by providing a structured, queryable interface for exploring endpoints, schemas, tags, and API metadata. It includes 14 tools designed for API discovery, endpoint details, curl command generation, schema analysis, and even safe execution against a live API. This lets models like Claude understand and reason about an API without needing to interpret raw documentation, enabling tasks such as curl generation, endpoint lookups, and impact analysis directly from the OpenAPI spec. To use it, run the MCP server (for example via npx) and configure your MCP consumer to point at the provided server to access the available tools and data.

Prerequisites:

• Node.js (v18+) and npm installed on your system
• Internet access to fetch the MCP package

Install the MCP Swagger server globally:

npm install -g @awssam/mcp-swagger

Run the server locally (example using the Petstore OpenAPI document):

npx @awssam/mcp-swagger https://petstore.swagger.io/v2/swagger.json

Alternatively, run via Claude CLI configuration as shown in the Quick Start:

# Claude CLI (Recommended) - add via CLI or config
claude mcp add swagger npx @awssam/mcp-swagger https://petstore.swagger.io/v2/swagger.json

Or place the configuration in Claude's YAML config and restart Claude:

mcpServers:
  swagger:
    command: npx
    args:
      - "@awssam/mcp-swagger"
      - "https://petstore.swagger.io/v2/swagger.json"

If you have a local API URL, you can export it and run:

export API_URL=https://your-api.com/api-docs
npx @awssam/mcp-swagger

Tips and notes:

• The server supports OpenAPI 3.0 and is compatible with Swagger 2.0 endpoints.
• It caches fetched Swagger documents automatically for faster responses.
• Use the executeEndpoint tool to test endpoints and fetch live responses when needed.
• Ensure your OpenAPI URL is publicly reachable or accessible from where the MCP server runs.
• If you customize environment variables, document them in your deployment config (e.g., API_URL, CACHE_TTL).
• If endpoints change, reload the MCP server or clear the cache to fetch the latest OpenAPI document.
• Useful for integration with Claude’s mcp workflow via the 14 available tools (listEndpoints, getEndpointDetails, searchEndpoints, etc.).