Overview

The Swagger-MCP server enables AI models to interact with any API by leveraging its Swagger/OpenAPI specification. It automatically generates MCP tools from API definitions, allowing AI agents to discover endpoints, understand data models, and interact with APIs dynamically without manual tool configuration.

Key Features

⬇️

Swagger Definition Download

Downloads and stores Swagger specifications locally for faster reference

🛠️

Automatic Tool Generation

Generates complete MCP tool definitions with full schema information from Swagger specs

🧠

AI-Specific Instructions

Includes AI-specific instructions in tool descriptions to guide AI agents

📄

Endpoint & Model Listing

Returns lists of all endpoints, their HTTP methods, descriptions, and defined models

🔄

YAML & JSON Support

Supports both JSON and YAML Swagger definition files

⚙️

Improved Tool Code Generator

Enhanced generator with complete schema information, better parameter naming, and semantic tool names

Available Tools

Quick Reference

Tool	Purpose	Category
`getSwaggerDefinition`	Downloads a Swagger definition from a URL	Definition Management
`listEndpoints`	Lists all endpoints from the Swagger definition	Discovery
`listEndpointModels`	Lists all models used by a specific endpoint	Discovery
`generateModelCode`	Generates TypeScript code for a model	Code Generation
`generateEndpointToolCode`	Generates TypeScript code for an MCP tool definition	Code Generation

Detailed Usage

getSwaggerDefinition▶

Downloads a Swagger definition from a given URL and stores it locally for the MCP server to use.

use_mcp_tool({
  server_name: "swagger",
  tool_name: "getSwaggerDefinition",
  arguments: {
    swaggerUrl: "https://petstore.swagger.io/v2/swagger.json"
  }
});

This tool is crucial for initializing the server with the target API's specification.

listEndpoints▶

Retrieves a list of all API endpoints defined in the loaded Swagger specification, including their HTTP methods and descriptions.

use_mcp_tool({
  server_name: "swagger",
  tool_name: "listEndpoints",
  arguments: {}
});

Useful for discovering available API functionalities.

listEndpointModels▶

Lists all data models (schemas) that are used by a specific API endpoint.

use_mcp_tool({
  server_name: "swagger",
  tool_name: "listEndpointModels",
  arguments: {
    endpointPath: "/pets/{id}",
    httpMethod: "GET"
  }
});

Helps in understanding the data structures involved in an API call.

generateModelCode▶

Generates TypeScript code for a specified data model from the Swagger definition.

use_mcp_tool({
  server_name: "swagger",
  tool_name: "generateModelCode",
  arguments: {
    modelName: "Pet"
  }
});

Facilitates client-side code generation and type safety.

generateEndpointToolCode▶

Generates TypeScript code for an MCP tool definition corresponding to a specific API endpoint.

use_mcp_tool({
  server_name: "swagger",
  tool_name: "generateEndpointToolCode",
  arguments: {
    endpointPath: "/pets",
    httpMethod: "POST"
  }
});

This tool provides the MCP client with the necessary schema and instructions to call the API endpoint.

Installation

To set up the Swagger-MCP server, follow these steps:

Clone the repository:

git clone https://github.com/Vizioz/Swagger-MCP.git
cd Swagger-MCP

Install dependencies:
```
npm install
```
Build the application:
```
npm run build
```
This compiles the TypeScript code, preparing it to be used as an MCP Server.
Run as an MCP Server:
```
node build/index.js
```
The server will run, ready for integration with MCP clients.

Common Use Cases

1. Dynamic API Interaction

Enable AI models to interact with any API by simply providing its Swagger specification, allowing for dynamic tool generation and execution based on the API's capabilities.

2. API Development & Testing with AI

Utilize AI to assist in API development by generating code for models and tools, and to facilitate testing by enabling AI to make requests and validate responses against the Swagger specification.

3. Automated Documentation & Code Generation

Leverage AI to generate interactive API documentation and client-side code (e.g., TypeScript types) directly from the Swagger specification, ensuring consistency and reducing manual effort.

4. AI-Driven API Exploration

Allow AI agents to explore and understand new APIs by listing endpoints, models, and generating detailed tool definitions, accelerating integration and usage.

OpenAPI/Swagger MCP Server