MCP 服务器

mcp-swagger

Exposes Swagger/OpenAPI API documentation to AI models, enabling exploration, search, and interaction with endpoints, schemas, and execution of API calls.

README

@awssam/mcp-swagger

MCP (Model Context Protocol) server for exposing Swagger/OpenAPI documentation to AI models like Claude. This tool allows AI assistants to explore, understand, and interact with your API documentation seamlessly.

Features

14 Powerful Tools for exploring API documentation
Automatic Caching for fast responses
OpenAPI 3.0 Support (Swagger 2.0 compatible)
Token-Optimized responses for efficient AI interactions
Search & Discovery with intelligent scoring
Path Validation with typo suggestions
Curl Generation with example payloads
Schema Analysis and reference tracking

Installation

npm install -g @awssam/mcp-swagger

Quick Start

Using with Claude Desktop

Add to your Claude Desktop configuration file:

MacOS: ~/Library/Application Support/Claude/claude_desktop_config.json Windows: %APPDATA%\Claude\claude_desktop_config.json

{
  "mcpServers": {
    "swagger": {
      "command": "npx",
      "args": [
        "@awssam/mcp-swagger",
        "https://petstore.swagger.io/v2/swagger.json"
      ]
    }
  }
}

Using with Claude CLI (Claude Code)

Option 1: Using claude mcp add command (Recommended)

claude mcp add swagger npx @awssam/mcp-swagger https://petstore.swagger.io/v2/swagger.json

Option 2: Manual Configuration

Add to your Claude CLI configuration file:

Location: ~/.config/claude/config.yaml

mcpServers:
  swagger:
    command: npx
    args:
      - "@awssam/mcp-swagger"
      - "https://petstore.swagger.io/v2/swagger.json"

Or if installed globally:

mcpServers:
  swagger:
    command: mcp-swagger
    args:
      - "https://petstore.swagger.io/v2/swagger.json"

After adding the configuration, restart Claude CLI for the changes to take effect.

Using with Environment Variable

export API_URL=https://your-api.com/api-docs
npx @awssam/mcp-swagger

Using as CLI

npx @awssam/mcp-swagger https://your-api.com/api-docs

Available Tools

1. `listEndpoints`

Lists all available API endpoints with their HTTP methods and tags.

Parameters:

tag (optional): Filter by specific tag

Example:

{
  "tag": "users"
}

2. `getEndpointDetails`

Retrieves complete details of a specific endpoint including parameters, request body, responses, and schemas.

Parameters:

path (required): Endpoint path (e.g., /users/{id})
method (optional): HTTP method (get, post, put, delete, patch)

Example:

{
  "path": "/users/{id}",
  "method": "get"
}

3. `searchEndpoints`

Searches for endpoints by keyword in paths, descriptions, and tags. Results are sorted by relevance.

Parameters:

query (required): Search term

Example:

{
  "query": "authentication"
}

4. `getSchemas`

Retrieves data schemas (DTOs) defined in the API. Without parameters, lists all available schemas.

Parameters:

schemaName (optional): Specific schema name to retrieve

Example:

{
  "schemaName": "User"
}

5. `listTags`

Lists all tags used to categorize endpoints in the API.

6. `getEndpointsByTag`

Retrieves all endpoints associated with a specific tag.

Parameters:

tag (required): Tag name

Example:

{
  "tag": "authentication"
}

7. `getApiInfo`

Retrieves API metadata including title, version, description, servers, contact info, and license.

8. `getSecuritySchemes`

Lists authentication/authorization schemes available (OAuth2, API keys, Bearer tokens, etc.).

9. `getServerUrls`

Retrieves available server URLs and their environments (dev, staging, prod, etc.).

10. `validateEndpointPath`

Checks if an endpoint path exists. If not found, suggests similar paths to help with typos.

Parameters:

path (required): Endpoint path to validate

Example:

{
  "path": "/users/{id}"
}

11. `getSchemaReferences`

Finds all endpoints that use a specific schema. Useful for impact analysis when modifying schemas.

Parameters:

schemaName (required): Schema name to search for

Example:

{
  "schemaName": "User"
}

12. `generateCurlExample`

Generates a curl command example for a specific endpoint, including headers and sample request body.

Parameters:

path (required): Endpoint path
method (required): HTTP method

Example:

{
  "path": "/users",
  "method": "post"
}

13. `getDeprecatedEndpoints`

Lists all endpoints marked as deprecated. Useful for migration planning.

14. `executeEndpoint`

✨ NEW - Executes an API endpoint and returns the actual response. Automatically uses required headers from the Swagger spec. Perfect for testing endpoints and fetching real-time data.

Parameters:

path (required): Endpoint path (e.g., /users/{id})
method (required): HTTP method (get, post, put, delete, patch)
baseUrl (optional): Base server URL (uses Swagger default if not provided)
pathParams (optional): Path parameters object (e.g., {"id": "123"})
queryParams (optional): Query parameters object (e.g., {"page": 1, "perPage": 10})
headers (optional): Custom headers object (e.g., {"Authorization": "Bearer token"})
body (optional): Request body for POST/PUT/PATCH

Example:

{
  "path": "/admin/organizations",
  "method": "get",
  "baseUrl": "http://localhost:4000",
  "queryParams": {
    "page": 1,
    "perPage": 10
  },
  "headers": {
    "x-dev-code": "ILoveMom"
  }
}

Response includes:

success: Boolean indicating if request succeeded
status: HTTP status code
statusText: HTTP status message
data: Response body (parsed JSON or text)
headers: Response headers
url: Full URL that was called
method: HTTP method used

Project Structure

src/
├── index.js                 # Entry point & server setup
├── config.js               # Configuration management
├── swagger/
│   ├── fetcher.js          # Swagger doc fetching & caching
│   └── parser.js           # Endpoint, schema, and tag parsing
└── tools/
    ├── definitions.js      # Tool schemas & definitions
    └── handlers.js         # Tool request handlers

Configuration

The server accepts the API URL in three ways (in order of precedence):

Command-line argument: npx @awssam/mcp-swagger <URL>
Environment variable: export API_URL=<URL>
Default: http://localhost:3000/api-json

Requirements

Node.js >= 18.0.0
Valid Swagger/OpenAPI JSON or YAML endpoint

Use Cases

API Exploration: Let AI understand and navigate your API
Documentation Assistance: Get instant answers about endpoints
Code Generation: Generate curl commands and examples
Migration Planning: Find deprecated endpoints
Impact Analysis: Track schema usage across endpoints
Developer Onboarding: Quick API discovery and learning

Development

# Clone the repository
git clone https://github.com/awssam/mcp-swagger.git
cd mcp-swagger

# Install dependencies
npm install

# Run locally
npm start https://petstore.swagger.io/v2/swagger.json