Swagger MCP Server
# 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
Scored across 4 tools
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.
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.
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.
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.