Swagger MCP

Automatically convert a Swagger/OpenAPI specification into an MCP server for use with Windsurf, Cursor, or other tools.

Quickstart

swagger-mcp uses pipx

Install from PyPI using pipx (recommended):

Alternatively, install from source:

Confirm the installation succeeded:

Spin up a sample "products and product categories" API on your local machine on port 9000:

Visit http://localhost:9000/docs to confirm the sample server is running.

We'll use this sample server to show how to configure an MCP server in Windsurf.

Make sure the sample server is running before following the Windsurf or Cursor instructions below.

Windsurf

Start an MCP Server in Windsurf (Windsurf Settings -> Settings -> Cascade -> Manage Plugins -> View Raw Config):

That's it! Your API is now accessible through Windsurf, Cursor, or other tools as a set of AI-friendly tools.

Ask your AI agent to list, create, update, and delete products and categories.

Cursor (>=v0.46)

Support for Cursor is still in beta as Cursor MCP integration matures. Windsurf is currently the preferred experience. To add a custom MCP server in Cursor, go to Settings -> Cursor Settings -> Tools & Integrations -> Add Custom MCP.

Please Note: In Cursor, you may need to replace the command

Also note the --cursor flag. This is for Cursor compatibility.

Again, MCP integration is currently in beta in Cursor as of v0.46 and may not work as expected. Currently, Windsurf is a better experience in general.

See other examples in Other Fun Servers.

Additional Options

1. You can pass a JSON file, YAML file, or URL for the --spec option:

   • /path/to/openapi.json

   • /path/to/openapi.yaml

   • https://api.example.com/openapi.json

2. Filter endpoints: Only include endpoints where the path matches the regex pattern:

3. Filter endpoints: Exclude endpoints where the path matches the regex pattern:

4. Authentication

5. Custom headers

6. Server URLs If the OpenAPI spec already contains a specific server URL, you don't have to provide it as a command line argument. But if you do, the command line --server-url overrides all endpoints.

7. Constant Values

If you want to always automatically provide a value for a parameter, you can use the --const option. You can include as many --const options as you need.

Supported Features

• All HTTP methods (GET, POST, PUT, DELETE, etc.)

• Path parameters

• Query parameters

• Textual Multi-Part Request Body Fields

• JSON Request body

• Bearer Token Authentication

• Custom Headers

• Constant Values

Limitations

• Endpoints that have recursive schema references are not yet supported.

• Cursor MCP integration is very early and frankly broken. I try to address some of these with cursor mode --cursor, but it's still not great. Until Cursor MCP support gets better, you'll be happier with Windsurf.

• We will never support automatic OAuth workflow execution. If the OAuth workflow creates a bearer token, you must obtain this token yourself by performing OAuth out-of-band, and provide this bearer token as a command line argument.

• We do not support Swagger/OpenAPI specifications spread across multiple files (i.e.; fragments, extensions, etc.).

• We do not support path variable substitution in server URLs (but we do support path variables in endpoints).

• In general, we do not support all Swagger/OpenAPI features. The Swagger/OpenAPI standard is vast, and support for more obscure features will be added as needed / requested.

Help

• If you have trouble spinning up a server, try the following command: REAL_LOGGER=true swagger-mcp-parse-dry-run ... and provide all the same arguments you would use to spin up a server. Include this information in any issue you file.

• If you find a Swagger API specification that is not supported and you can't use any of the available parameters for a workaround, please file an issue. We will add support for it as needed / requested.

Command Line Options

• --spec (required): Path or URL to your OpenAPI/Swagger specification

• --name (required): Name for your MCP server (shows up in Windsurf/Cursor)

• --server-url: Base URL for API calls (overrides servers defined in spec)

• --bearer-token: Bearer token for authenticated requests

• --additional-headers: JSON string of additional headers to include in all requests

• --include-pattern: Regex pattern to include only specific endpoint paths (e.g., "/api/v1/.*")

• --exclude-pattern: Regex pattern to exclude specific endpoint paths (e.g., "/internal/.*")

• --header: key:value pair of an extra header to include with all requests. Can be included multiple times to specify multiple headers.

• --const: key:value pair of a constant value to always use for a parameter, if the parameter is present on the endpoint (can be a path variable, query parameter, top-level request body property, or multi-part non-file form data field). Can be included multiple times to specify multiple const values.

• --cursor: Run in cursor mode

Authentication

For APIs requiring authentication:

Other Fun Servers

Countries

Petstore

For Developers

Installation

For development, install with development dependencies:

For a global installation on your local machine, use:

Unit Tests

Integration Tests

MCP Inspector (For interactive exploration of the MCP Server)

You'll have to do a global installation of your latest code first (bash scripts/install-global.sh), then you can run the inspector script.

You'll see the server type STDIO and the command swagger-mcp pre-filled.

Click "Connect" and then "List Tools" to begin interacting with your MCP Server.

Logging

To run the server with logs enabled, set the REAL_LOGGER environment variable to true: