article

README

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

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

Clone the repository:

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

Install dependencies:

yarn install

Create a .env file based on the example:

cp .env.example .env

Configure your Swagger/OpenAPI specification:
- Place your Swagger file in the project (e.g., swagger.json)
- Or provide a URL to your Swagger specification
Update the configuration in config.json with your server settings:

{
  "server": {
    "host": "localhost",
    "port": 3000
  },
  "swagger": {
    "url": "url-or-path/to/your/swagger.json",
    "apiBaseUrl": "https://api.example.com",  // Fallback if not specified in Swagger
    "defaultAuth": {  // Fallback if not specified in Swagger
      "type": "apiKey",
      "apiKey": "your-api-key",
      "apiKeyName": "api_key",
      "apiKeyIn": "header"
    }
  }
}

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

Start the development server:

yarn dev

Build for production:

yarn build

Start the production server:

yarn start

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:

# Run tests once
yarn test

# Run tests in watch mode
yarn test:watch

# Run tests with coverage report
yarn test:coverage

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

{
  "defaultAuth": {
    "type": "basic",
    "username": "your-username",
    "password": "your-password"
  }
}

Bearer Token

{
  "defaultAuth": {
    "type": "bearer",
    "token": "your-bearer-token"
  }
}

API Key

{
  "defaultAuth": {
    "type": "apiKey",
    "apiKey": "your-api-key",
    "apiKeyName": "X-API-Key",
    "apiKeyIn": "header"
  }
}

OAuth2

{
  "defaultAuth": {
    "type": "oauth2",
    "token": "your-oauth-token"
  }
}

Development

Start the development server:

yarn dev

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

swagger-mcp