License

Skip to content

You signed in with another tab or window. Reload
to refresh your session. You signed out in another tab or window. Reload
to refresh your session. You switched accounts on another tab or window. Reload
to refresh your session. Dismiss alert

dcolley / swagger-mcp Public

• Notifications
  You must be signed in to change notification settings

• Fork 1

• Star 23

Swagger to MCP server

License

Apache-2.0 license

23 stars
1 fork
Branches
Tags
Activity

Star

Notifications
You must be signed in to change notification settings

dcolley/swagger-mcp

main

1 Branch
0 Tags

Go to file

Code

Folders and files

| Name | | Name | Last commit message | Last commit date |
| --- | --- | --- | --- |
| Latest commit
-------------



Derek Colley

update readme

Mar 13, 2025

6f4e510
 · Mar 13, 2025

History
-------

6 Commits

| | |
| examples | | examples | Initial commit: Swagger MCP server implementation with tests | Mar 13, 2025 |
| src | | src | Initial commit: Swagger MCP server implementation with tests | Mar 13, 2025 |
| tests | | tests | update readme | Mar 13, 2025 |
| .env.example | | .env.example | Initial commit: Swagger MCP server implementation with tests | Mar 13, 2025 |
| .gitignore | | .gitignore | Initial commit: Swagger MCP server implementation with tests | Mar 13, 2025 |
| LICENSE | | LICENSE | Initial commit | Mar 13, 2025 |
| README.md | | README.md | update readme | Mar 13, 2025 |
| config.json | | config.json | Initial commit: Swagger MCP server implementation with tests | Mar 13, 2025 |
| jest.config.js | | jest.config.js | Initial commit: Swagger MCP server implementation with tests | Mar 13, 2025 |
| package.json | | package.json | Initial commit: Swagger MCP server implementation with tests | Mar 13, 2025 |
| tsconfig.json | | tsconfig.json | Initial commit: Swagger MCP server implementation with tests | Mar 13, 2025 |
| yarn.lock | | yarn.lock | Initial commit: Swagger MCP server implementation with tests | Mar 13, 2025 |
| View all files | | |

Repository files navigation

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

1. Clone the repository:

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

1. Install dependencies:

yarn install

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

cp .env.example .env

1. 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

1. Start the development server:

yarn dev

1. Build for production:

yarn build

1. 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

1. 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

About

Swagger to MCP server

Resources

Readme

License

Apache-2.0 license

Activity

Stars

23 stars

Watchers

2 watching

Forks

1 fork

Report repository

Releases

No releases published

Packages 0

No packages published

Languages

• TypeScript 90.6%

• JavaScript 9.4%

You can’t perform that action at this time.