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, --doc-url <url>      URL to swagger documentation
  -f, --doc-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 --doc-url https://api.example.com/swagger.json --tool-prefix example --ignore-ssl

Load from local file

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

With authentication

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

Override base URL

mcp-swagger --doc-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
`--doc-url`	`SWAGGER_DOC_URL`	URL to swagger documentation
`--doc-file`	`SWAGGER_DOC_FILE`	Path to local swagger file
`--tool-prefix`	`SWAGGER_TOOL_PREFIX`	Custom prefix for generated tools
`--base-url`	`SWAGGER_BASE_URL`	Override base URL for API calls
`--ignore-ssl`	`SWAGGER_IGNORE_SSL=true`	Ignore SSL certificate errors
`--auth-header`	`SWAGGER_AUTH_HEADER`	Authentication header

Using Environment Variables

You can set environment variables to avoid passing command-line arguments repeatedly:

# Set environment variables
export SWAGGER_DOC_URL="https://api.example.com/swagger.json"
export SWAGGER_TOOL_PREFIX="myapi"
export SWAGGER_BASE_URL="https://staging.api.com"
export SWAGGER_IGNORE_SSL="true"
export SWAGGER_AUTH_HEADER="Bearer your-token-here"

# Run the server (will use environment variables)
mcp-swagger

Environment Variables in MCP Configuration

You can also use environment variables in your MCP client configuration:

{
  "mcpServers": {
    "swagger-api": {
      "command": "mcp-swagger",
      "env": {
        "SWAGGER_DOC_URL": "https://example.com/swagger.json",
        "SWAGGER_TOOL_PREFIX": "example",
        "SWAGGER_IGNORE_SSL": "true"
      }
    }
  }
}

MCP Integration

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

{
  "mcpServers": {
    "swagger-api": {
      "command": "mcp-swagger",
      "args": [
        "--doc-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