Swagger MCP Server

🚀 Swagger MCP Server

A server based on the Model Context Protocol (MCP) that parses Swagger/OpenAPI documents and generates TypeScript types and API client code.

🚀 Quick Start

Starting the Server

node start-server.js

Connecting with MCP Inspector

After starting the debugging server, you can connect using the following command:

npx @modelcontextprotocol/inspector pipe -- node start-server.js

Or use the direct method (which may cause output confusion):

npx @modelcontextprotocol/inspector -- node start-server.js

✨ Features

This server can parse Swagger and OpenAPI documents, and generate TypeScript type definitions and API client code based on these documents. It supports multiple client frameworks, including Axios, Fetch, and React Query, and provides optimization features to handle large API documents.

📦 Installation

Installing via Smithery

To automatically install the swagger-mcp-server for Claude Desktop via Smithery:

npx -y @smithery/cli install @tuskermanshu/swagger-mcp-server --client claude

💻 Usage Examples

Supported MCP Tools

1. parse-swagger - Parse Swagger/OpenAPI documents and return API operation information.
2. parse-swagger-optimized - Parse Swagger/OpenAPI documents (optimized version).
3. parse-swagger-lite - Lightweight parsing of Swagger/OpenAPI documents, optimized for large documents.
4. generate-typescript-types - Generate TypeScript type definitions from Swagger/OpenAPI documents.
5. generate-typescript-types-optimized - Generate TypeScript type definitions from Swagger/OpenAPI documents (optimized version).
6. generate-api-client - Generate API client code from Swagger/OpenAPI documents.
7. generate-api-client-optimized - Generate API client code from Swagger/OpenAPI documents (optimized version).
8. file-writer - Write content to the file system.

Handling Large Documents

For large API documents, it is recommended to use the following configuration:

1. Use optimized tools and enable caching and lazy loading.
2. Use tags or path prefixes for filtering to only retrieve the required API operations.
3. Only include schema definitions when necessary.
4. Set a reasonable cache validity period to avoid frequent re - parsing.

Example:

{
  "method": "parse-swagger-lite",
  "params": {
    "url": "https://your-large-api-doc-url.json",
    "useCache": true,
    "skipValidation": true,
    "lazyLoading": true,
    "filterTag": "your-specific-tag",
    "includeSchemas": false
  }
}

Supported Client Frameworks

• Axios: A feature - rich Promise - based HTTP client.
• Fetch: A native browser API that requires no additional dependencies.
• React Query: A data fetching and caching library for React applications, providing hooks and caching capabilities.

Example - Generating a React Query Client:

{
  "method": "generate-api-client-optimized",
  "params": {
    "swaggerUrl": "https://petstore3.swagger.io/api/v3/openapi.json",
    "outputDir": "./generated/react-query",
    "clientType": "react-query",
    "generateTypeImports": true
  }
}

Cache Management

The API document cache is stored in the .api-cache directory. If you need to clear the cache, delete the directory or set the useCache: false parameter.

Configuration Options

You can customize the server settings in swagger-mcp-config.json:

{
  "name": "Swagger MCP Server",
  "version": "1.0.0",
  "transport": "stdio"
}

📚 Documentation

Project Roadmap

For development plans and progress, please refer to the road.md file.

Building the Project

# Build using npm
npm run build

# Or use pnpm
pnpm build