Swagger MCP Server

A server that ingests and serves Swagger/OpenAPI specifications through the Model Context Protocol (MCP).

Features

• Loads Swagger/OpenAPI specifications

• Supports multiple authentication methods:

  • Basic Auth

  • Bearer Token

  • API Key (header or query)

  • OAuth2

• Automatically generates MCP tools from API endpoints

• Server-Sent Events (SSE) support for real-time communication

• TypeScript support

Related MCP server: Swagger MCP Server

Security

This is a personal server!! Do not expose it to the public internet. If the underlying API requires authentication, you should not expose the MCP server to the public internet.

TODO

• secrets - the MCP server should be able to use secrets from the user to authenticate requests to the API

• Comprehensive test suite

Prerequisites

• Node.js (v18 or higher)

• Yarn package manager

• TypeScript

Installation

1. Clone the repository:

2. Install dependencies:

3. Create a .env file based on the example:

4. Configure your Swagger/OpenAPI specification:

   • Place your Swagger file in the project (e.g., swagger.json)

   • Or provide a URL to your Swagger specification

5. Update the configuration in config.json with your server settings:

Note: The server prioritizes settings from the Swagger specification over the config file:

• If the Swagger file contains a servers array, the first server URL will be used as the base URL

• If the Swagger file defines security schemes, they will be used for authentication

• The config file settings serve as fallbacks when not specified in the Swagger file

Usage

1. Start the development server:

2. Build for production:

3. Start the production server:

API Endpoints

• GET /health - Check server health status

• GET /sse - Establish Server-Sent Events connection

• POST /messages - Send messages to the MCP server

Testing

Run the test suite:

Authentication

The server supports various authentication methods. Configure them in the config.json file as fallbacks when not specified in the Swagger file:

Basic Auth

Bearer Token

API Key

OAuth2

Development

1. Start the development server:

License

This project is licensed under the Apache 2.0 License.

Environment Variables

• PORT: Server port (default: 3000)

• API_USERNAME: Username for API authentication (fallback)

• API_PASSWORD: Password for API authentication (fallback)

• API_TOKEN: API token for authentication (fallback)

• DEFAULT_API_BASE_URL: Default base URL for API endpoints (fallback)

• DEFAULT_SWAGGER_URL: Default Swagger specification URL