Swagger API MCP server

This MCP server connects to Swagger specifications and helps AI assistants generate the necessary models and tool definitions to interact with the specified APIs. It streamlines the creation of MCP servers by automating the interpretation of Swagger documentation.

Installation

Prerequisites

• Node.js (v14 or higher)
• npm or yarn

Setup Steps

1. Clone the repository:

git clone https://github.com/readingdancer/swagger-mcp.git
cd swagger-mcp

2. Install dependencies:

npm install

3. Create and configure the environment file:

cp .env.example .env

4. Update the .env file with appropriate values:

   • PORT: The port on which the server will run (default: 3000)
   • NODE_ENV: The environment (development, production, test)
   • LOG_LEVEL: Logging level (info, error, debug)

5. Build the application:

npm run build

Usage

Running the MCP Server

Start the server after building:

node build/index.js

Using the MCP Inspector

For debugging purposes, you can run the MCP inspector:

npm run inspector

Integration with Cursor

To add this MCP server to Cursor:

1. Open Cursor Settings > Features > MCP
2. Click "+ Add New MCP Server"
3. Enter a name for the server (e.g., "Swagger MCP")
4. Select "stdio" as the transport type
5. Enter the command: node path/to/swagger-mcp/build/index.js
6. Click "Add"

The Swagger MCP tools will now be available to the Cursor Agent in Composer.

Available Tools

Swagger MCP Tools

• getSwaggerDefinition: Downloads a Swagger definition from a URL
• listEndpoints: Lists all endpoints from the Swagger definition
• listEndpointModels: Lists all models used by a specific endpoint
• generateModelCode: Generates TypeScript code for a model
• generateEndpointToolCode: Generates TypeScript code for an MCP tool definition

Swagger MCP Prompts

The server provides guided workflows through prompts. For example, to use the "add-endpoint" prompt:

{
  "method": "prompts/get",
  "params": {
    "name": "add-endpoint",
    "arguments": {
      "swaggerUrl": "https://petstore.swagger.io/v2/swagger.json",
      "endpointPath": "/pets/{id}",
      "httpMethod": "GET"
    }
  }
}

Working with Projects

Setting Up a New Project

To start working with a Swagger API:

1. Ask the agent to get the Swagger file by providing the URL
2. The MCP server will download the file and save it locally with a hashed filename
3. A .swagger-mcp settings file will be created in your project root

Configuration File

The .swagger-mcp file associates your project with a specific Swagger API:

SWAGGER_FILENAME = TheFilenameOfTheLocallyStoredSwaggerFile

Tool Code Generation

The MCP tool code generator creates comprehensive tool definitions with:

• Complete schema information for all models
• Semantic parameter and tool naming
• Support for both JSON and YAML Swagger definitions
• AI-specific instructions in tool descriptions

Example Code Generation

import generateEndpointToolCode from './services/generateEndpointToolCode.js';

const toolCode = await generateEndpointToolCode({
  path: '/pets',
  method: 'POST',
  swaggerFilePath: './petstore.json',
  singularizeResourceNames: true
});

console.log(toolCode);

How to add this MCP server to Cursor

There are two ways to add an MCP server to Cursor. The most common way is to add the server globally in the ~/.cursor/mcp.json file so that it is available in all of your projects.

If you only need the server in a single project, you can add it to the project instead by creating or adding it to the .cursor/mcp.json file.

Adding an MCP server to Cursor globally

To add a global MCP server go to Cursor Settings > MCP and click "Add new global MCP server".

When you click that button the ~/.cursor/mcp.json file will be opened and you can add your server like this:

{
    "mcpServers": {
        "cursor-rules-mcp": {
            "command": "npx",
            "args": [
                "-y",
                "cursor-rules-mcp"
            ]
        }
    }
}

Adding an MCP server to a project

To add an MCP server to a project you can create a new .cursor/mcp.json file or add it to the existing one. This will look exactly the same as the global MCP server example above.

How to use the MCP server

Once the server is installed, you might need to head back to Settings > MCP and click the refresh button.

The Cursor agent will then be able to see the available tools the added MCP server has available and will call them when it needs to.

You can also explictly ask the agent to use the tool by mentioning the tool name and describing what the function does.