Skip to main content
Glama
Swagger MCP Server

Swagger MCP Server

by tsiva18
README.md
# Swagger MCP Server (NestJS / TypeScript)

A production-ready [Model Context Protocol (MCP)](https://modelcontextprotocol.io/) server built with NestJS and TypeScript to inspect, search, and navigate Swagger / OpenAPI 2.x and 3.x specifications via stdio.

---

## πŸ“ Project Structure

```
swagger-mcp/
β”œβ”€β”€ src/
β”‚   β”œβ”€β”€ config/
β”‚   β”‚   └── swagger.config.ts    # ConfigModule loader for Swagger settings & auth
β”‚   β”œβ”€β”€ services/
β”‚   β”‚   └── swagger.service.ts   # Fetching, caching, parsing OpenAPI schemas & operations
β”‚   β”œβ”€β”€ tools/
β”‚   β”‚   └── swagger.tools.ts     # MCP tools registration (list, search, details, schema)
β”‚   β”œβ”€β”€ app.module.ts            # Root NestJS module wiring DI dependencies
β”‚   └── main.ts                  # Application bootstrap & StdioServerTransport setup
β”œβ”€β”€ .env                         # Local environment variables
β”œβ”€β”€ .env.example                 # Example configuration template
β”œβ”€β”€ package.json                 # Scripts and dependencies
└── tsconfig.json                # TypeScript NodeNext ESM compiler options
```

---

## βš™οΈ Configuration (`.env`)

Configure your Swagger/OpenAPI target URL and credentials in [.env](file:///c:/Users/Sivaram/Documents/swagger-mcp/.env):

```env
SWAGGER_URL=https://api.example.com/api-json
SWAGGER_USERNAME=example
SWAGGER_PASSWORD=example

# Optional: Bearer token authentication (takes precedence over basic auth if provided)
# SWAGGER_TOKEN=your-bearer-token-here
```

---

## πŸ› οΈ MCP Tools Provided

| Tool | Parameters | Description |
| :--- | :--- | :--- |
| `list_api_modules` | None | Lists all API tags/modules, API title, and version. |
| `search_api` | `query: string` | Searches endpoints by path, summary, description, operationId, or tags. |
| `get_api_details` | `path: string`, `method: string` | Returns full endpoint documentation (parameters, request body, responses). |
| `get_api_schema` | `schemaName: string` | Returns request/response DTO schemas from `definitions` or `components.schemas`. |

---

## πŸš€ Getting Started

### 1. Install Dependencies
```bash
npm install
```

### 2. Build TypeScript
```bash
npm run build
```

### 3. Run the Server
```bash
# Production mode (dist/main.js)
npm start

# Development mode (with live tsx execution)
npm run start:dev
```

---

## πŸ”Œ Connecting to MCP Clients

Add the server to your MCP client configuration (e.g., Claude Desktop, Cursor, Antigravity, or Cline):

### Using NPX (Recommended - No installation required)

```json
{
  "mcpServers": {
    "swagger-api-reference": {
      "command": "npx",
      "args": ["-y", "@tsiva18/swagger-mcp-server"],
      "env": {
        "SWAGGER_URL": "https://api.example.com/api-json",
        "SWAGGER_USERNAME": "example",
        "SWAGGER_PASSWORD": "example"
      }
    }
  }
}
```

### Using Local Source

```json
{
  "mcpServers": {
    "swagger-api-reference": {
      "command": "node",
      "args": ["c:/Users/Sivaram/Documents/swagger-mcp/dist/main.js"],
      "env": {
        "SWAGGER_URL": "https://api.example.com/api-json",
        "SWAGGER_USERNAME": "example",
        "SWAGGER_PASSWORD": "example"
      }
    }
  }
}
```

> **Note on Stdio Isolation**: NestJS logs are directed strictly to `stderr` through a custom `StderrLogger`, guaranteeing that `stdout` remains reserved solely for clean MCP JSON-RPC protocol frames.

TDQS

B3.4/5.0

Scored across 4 tools

Disambiguation5/5

Each tool targets a distinct stage of exploring a Swagger spec: listing modules, searching endpoints, retrieving endpoint details, and fetching DTO schemas. Search vs. get_api_details could superficially overlap, but the descriptions make clear one returns matches while the other returns full documentation for a specific endpoint.

Naming Consistency4/5

All names use snake_case with verb-first phrasing (list_api_modules, search_api, get_api_details, get_api_schema), which is predictable. The minor deviation is search_api, which omits the noun suffix and breaks the verb_api_noun pattern used by the other three.

Tool Count4/5

Four tools are appropriately lean for a read-only Swagger documentation server, with no redundant entries. It is on the thin sideβ€”one more tool (e.g., listing endpoints within a module) would make the surface feel complete rather than minimal.

Completeness4/5

The core consumption workflowβ€”discover modules, search endpoints, read full details, resolve schemasβ€”is fully covered. Minor gaps remain: no way to enumerate all endpoints in a module without a search query, and no tool for global definitions or servers, but agents can work around these.

Maintenance

ActivityMaintained
ResponsivenessNo recent community issues