MCP Swagger Server

An MCP (Model Context Protocol) server that automatically converts REST APIs with Swagger/OpenAPI documentation into MCP tools, making them accessible to MCP-compatible clients.

Features

🔄 Automatic Tool Generation: Converts Swagger/OpenAPI endpoints to MCP tools
🔒 SSL Certificate Handling: Option to ignore SSL certificate errors for internal APIs
🏷️ Custom Tool Prefixes: Organize tools with custom prefixes for better organization
📡 Stdio Transport: Uses stdio format as the default transport mechanism
🌐 Flexible Input: Supports both URL and local file swagger documentation
🔧 Parameter Support: Handles path, query, and body parameters
📝 Type Mapping: Maps Swagger types to JSON Schema types for proper validation

Installation

Global Installation

npm install -g mcp-swagger

From Source

git clone https://github.com/HainanZhao/mcp-swagger.git
cd mcp-swagger
npm install
npm run build

Usage

Command Line Options

mcp-swagger [options]

Options:
  -u, --swagger-url <url>      URL to swagger documentation
  -f, --swagger-file <file>    Path to local swagger file
  -p, --tool-prefix <prefix>   Custom prefix for generated tools
  -b, --base-url <url>         Override base URL for API calls
  --ignore-ssl                 Ignore SSL certificate errors
  -a, --auth-header <header>   Authentication header (e.g., "Bearer token")
  -h, --help                   Display help information
  -V, --version                Display version number

Examples

Load from URL with custom prefix

mcp-swagger --swagger-url https://api.example.com/swagger.json --tool-prefix example --ignore-ssl

Load from local file

mcp-swagger --swagger-file ./api-docs.json --tool-prefix local-api

With authentication

mcp-swagger --swagger-url https://api.example.com/swagger.json --auth-header "Bearer your-token-here"

Override base URL

mcp-swagger --swagger-file ./swagger.json --base-url https://staging.api.com --tool-prefix staging

Configuration

The server can be configured through command-line arguments or environment variables:

CLI Option	Environment Variable	Description
`--swagger-url`	`SWAGGER_URL`	URL to swagger documentation
`--swagger-file`	`SWAGGER_FILE`	Path to local swagger file
`--tool-prefix`	`TOOL_PREFIX`	Custom prefix for generated tools
`--base-url`	`BASE_URL`	Override base URL for API calls
`--ignore-ssl`	`IGNORE_SSL=true`	Ignore SSL certificate errors
`--auth-header`	`AUTH_HEADER`	Authentication header

MCP Integration

Add to your Agent configuration (e.g. claude_desktop_config.json or ~/.gemini/settings.json):

{
  "mcpServers": {
    "swagger-api": {
      "command": "mcp-swagger",
      "args": [
        "--swagger-url", "https://example.com/swagger.json",
        "--tool-prefix", "example",
        "--ignore-ssl"
      ]
    }
  }
}

Other MCP Clients

The server uses the standard MCP stdio transport, so it should work with any MCP-compatible client. Start the server and connect via stdin/stdout.

Generated Tools

Tool Naming Convention

Tools are named using the following pattern:

{prefix}_{method}_{path_segments}
Path parameters are converted to by_{parameter_name}

Examples:

GET /v1/users/ → myapi_get_v1_users
GET /v1/users/{id} → myapi_get_v1_users_by_id
POST /v1/users/ → myapi_post_v1_users

Parameter Mapping

Path parameters: Included in the URL path
Query parameters: Added as URL query string
Body parameters: Sent as JSON request body
Header parameters: Added to request headers

Type Mapping

Swagger Type	JSON Schema Type
`string`	`string`
`integer`	`number`
`boolean`	`boolean`
`array`	`array`
`object`	`object`

Sample Swagger Document

The server has been tested with the following sample swagger document structure:

{
  "swagger": "2.0",
  "info": {
    "title": "API Documentation",
    "version": "1.0"
  },
  "host": "api.example.com",
  "basePath": "/api",
  "paths": {
    "/v1/hosts/": {
      "get": {
        "summary": "Get a list of hosts",
        "parameters": [
          {
            "name": "filter_by",
            "in": "query",
            "type": "string",
            "description": "Filter criteria"
          }
        ]
      }
    },
    "/v1/hosts/{name}": {
      "get": {
        "summary": "Get host by name",
        "parameters": [
          {
            "name": "name",
            "in": "path",
            "required": true,
            "type": "string"
          }
        ]
      }
    }
  }
}

This would generate tools like:

example_get_v1_hosts - List hosts with optional filtering
example_get_v1_hosts_by_name - Get specific host by name

Error Handling

The server includes comprehensive error handling:

SSL Certificate Errors: Can be ignored with --ignore-ssl flag
Network Errors: Returned as error responses with details
Invalid Swagger: Validation errors are reported during startup
Missing Parameters: Parameter validation based on swagger schema
HTTP Errors: API response errors are captured and returned

Development

Building

npm run build

Testing

# Test with sample swagger file
npm run test

Linting

npm run lint

Troubleshooting

Common Issues

SSL Certificate Errors
- Use --ignore-ssl flag for internal APIs with self-signed certificates
Tool Name Conflicts
- Use --tool-prefix to add unique prefixes to avoid naming conflicts
Base URL Issues
- Use --base-url to override the base URL from swagger documentation
Authentication Failures
- Provide proper authentication header with --auth-header

Debug Mode

The server logs important information to stderr:

Swagger document loading status
Number of tools generated
Tool generation details

License

MIT License - see LICENSE file for details.

Contributing

Fork the repository
Create a feature branch
Make your changes
Add tests if applicable
Submit a pull request

Support

For issues and questions:

Create an issue on GitHub
Check the troubleshooting section above
Review the sample configurations

This server cannot be installed

security - not tested

license - permissive license

quality - not tested

How are these scores calculated?

hybrid server

The server is able to function both locally and remotely, depending on the configuration or use case.

Automatically converts REST APIs with Swagger/OpenAPI documentation into MCP tools, making any documented API accessible to MCP-compatible clients. Supports authentication, SSL handling, and flexible configuration for seamless API integration.

Related MCP Servers

Swagger MCP Server
dcolley
-
security
A
license
-
quality
A server that enables interaction with any API that has a Swagger/OpenAPI specification through Model Context Protocol (MCP), automatically generating tools from API endpoints and supporting multiple authentication methods.
Last updated -
15
94
TypeScript
Apache 2.0
OpenAPI to MCP Server
TykTechnologies
A
security
A
license
A
quality
A tool that creates MCP (Model Context Protocol) servers from OpenAPI/Swagger specifications, enabling AI assistants to interact with your APIs.
Last updated -
3
8
21
TypeScript
MIT License
OpenAPI to MCP Server
jeweis
-
security
F
license
-
quality
A service that converts OpenAPI specifications into MCP tools, enabling AI assistants to interact with your API endpoints through natural language.
Last updated -
Python
Universal MCP Tool
suhuail
-
security
F
license
-
quality
A versatile tool that converts Web API interfaces into MCP tools for AI assistants, allowing them to access various web services through simple configuration and API key management.
Last updated -
24
Python

View all related MCP servers

MCP Swagger Server