Swagger MCP Server

A Model Context Protocol (MCP) server that brings OpenAPI/Swagger documentation directly into your AI assistant. Point it at any Swagger/OpenAPI JSON URL and instantly get endpoint discovery, deep inspection, cURL generation, and TypeScript type generation — all inside Cursor or Claude.

---

Table of Contents

• Overview
• Features
• How It Works
• Prerequisites
• Installation
• Setup in Cursor
• Setup in Claude Desktop
• MCP Inspector (Debug)
• Available Tools
• Available Prompts
• Typical Workflow
• Project Structure
• Environment Variables
• Troubleshooting

---

Overview

The Swagger MCP Server acts as a bridge between your AI assistant and any REST API documented with OpenAPI 3.x or Swagger 2.x. Once registered as an MCP server in Cursor or Claude Desktop, it exposes a set of tools and prompts that let your AI:

• Fetch and cache an OpenAPI spec from a URL
• Browse all available API endpoints grouped by tag
• Inspect full endpoint contracts (parameters, request body, responses) with $ref resolution
• Generate ready-to-run curl commands with schema-derived sample bodies
• Generate copy-paste TypeScript interfaces and types from response/request schemas

The server runs over stdio transport (standard input/output), which is the native transport for MCP in Cursor and Claude Desktop.

---

Features

Feature	Description
Spec fetching & caching	Downloads OpenAPI JSON and caches it locally under doc/
Endpoint discovery	Lists all endpoints grouped by OpenAPI tags
Deep inspection	Full parameter, request body, and response details with recursive $ref resolution
cURL generation	Executable curl commands with placeholder values derived from the schema
TypeScript types	Generates interface or type aliases for request/response shapes
Guided prompts	Step-by-step AI workflow prompts for setup, exploration, implementation, and testing
Multi-project support	Register multiple API projects and switch between them instantly
Persistent state	Remembers all registered projects and the active one across server restarts

---

How It Works

AI Client (Cursor / Claude Desktop)
         │
         │  stdio  (MCP protocol)
         ▼
  swagger-mcp-server  (src/server.ts)
         │
         ├── Tools ──► utility + helpers
         │                  │
         │                  ▼
         │            doc/*.json          ← cached OpenAPI spec
         │            doc/.project-config.json  ← active project state
         │
         └── Prompts ──► guided AI instructions

First-use flow

1. Call generate-swagger-json with a projectName and swaggerUrl
2. Server fetches the JSON spec, validates it, and saves it under doc/
3. A grouped summary (-grouped.json) is also saved for fast browsing
4. The project is added to doc/.project-config.json and set as active

Subsequent calls

• All other tools read from the cached spec for the active project — no network calls needed
• State is restored automatically from doc/.project-config.json on server start

Multi-project flow

• Register as many projects as you need — each call to generate-swagger-json adds a new entry
• Use list-projects to see all registered projects and which is active
• Use switch-project to change the active project — all tools immediately use the new project's spec

---

Prerequisites

• Node.js v18 or later
• npm v9 or later
• An OpenAPI/Swagger spec accessible at a direct JSON URL (not the Swagger UI HTML page)

---

Installation

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

# 2. Install dependencies
npm install

# 3. (Optional) copy the env sample
cp .env.sample .env

No build step is required for local use — the server runs directly via tsx.

To verify the server starts correctly:

npm start

You should see the server start with no errors. Press Ctrl+C to stop it.

---

Setup in Cursor

Cursor supports MCP servers through its MCP configuration file. You can configure the Swagger MCP server at either the global level (available in all projects) or the project level.

Global configuration (recommended)

Open or create the Cursor MCP config file at:

~/.cursor/mcp.json

Add the following entry under mcpServers:

{
  "mcpServers": {
    "swagger-mcp": {
      "command": "node",
      "args": [
        "/absolute/path/to/swagger/node_modules/tsx/dist/cli.mjs",
        "/absolute/path/to/swagger/src/server.ts"
      ],
      "cwd": "/absolute/path/to/swagger"
    }
  }
}

Replace /absolute/path/to/swagger with the actual path to this repository. For example:

{
  "mcpServers": {
    "swagger-mcp": {
      "command": "node",
      "args": [
        "/Users/yourname/projects/swagger/node_modules/tsx/dist/cli.mjs",
        "/Users/yourname/projects/swagger/src/server.ts"
      ],
      "cwd": "/Users/yourname/projects/swagger"
    }
  }
}

Project-level configuration

Create a .cursor/mcp.json file in the root of your project with the same structure as above.

Enabling the server in Cursor

1. Open Cursor Settings (Cmd+,)
2. Navigate to Features → MCP
3. You should see swagger-mcp listed — toggle it on
4. Restart Cursor or reload the window (Cmd+Shift+P → Developer: Reload Window)

Verifying it works

Open a Cursor chat and type:

Use the setup-project prompt to get started

Or invoke a tool directly:

Call the available-api-endpoints tool

If the server is running correctly, the AI will respond with results from your cached API spec.

---

Setup in Claude Desktop

Claude Desktop uses the same MCP configuration format.

Locate the config file

Platform	Path
macOS	~/Library/Application Support/Claude/claude_desktop_config.json
Windows	%APPDATA%\Claude\claude_desktop_config.json

Add the server

Open (or create) the config file and add:

{
  "mcpServers": {
    "swagger-mcp": {
      "command": "node",
      "args": [
        "/absolute/path/to/swagger/node_modules/tsx/dist/cli.mjs",
        "/absolute/path/to/swagger/src/server.ts"
      ],
      "cwd": "/absolute/path/to/swagger"
    }
  }
}

Restart Claude Desktop

Fully quit and reopen Claude Desktop. The MCP server will start alongside it.

Verifying it works

In a Claude conversation, you can ask:

List all available API endpoints

Or use a prompt:

Use the explore-api prompt

Claude will use the swagger-mcp tools to answer from your cached spec.

---

MCP Inspector (Debug)

The MCP Inspector is a browser-based tool for testing MCP servers interactively. It lets you call tools and prompts manually, inspect inputs/outputs, and debug issues.

npm run inspector

This launches the Inspector against the running server. Open the URL shown in the terminal (usually http://localhost:5173) and you can:

• Browse all registered tools and prompts
• Fill in arguments and execute tool calls
• See raw JSON responses

---

Available Tools

Tools are callable functions exposed to the AI. All tools read from the locally cached OpenAPI spec (except generate-swagger-json which fetches from the network).

generate-swagger-json

Must be called first. Fetches the OpenAPI spec from a URL and caches it locally.

Argument	Type	Required	Description
projectName	string	Yes	A short name for this API project (e.g. medex, stripe)
swaggerUrl	string	Yes	Direct URL to the OpenAPI JSON spec (not the Swagger UI page)

Returns: Saved file paths, API title, version, and total endpoint count.

Example:

Generate swagger JSON for projectName "myapi" and swaggerUrl "https://api.example.com/api-docs-json"

---

list-projects

Lists all API projects that have been registered via generate-swagger-json.

Argument	Type	Required	Description
(none)	—	—	—

Returns: All projects with their name, JSON URL, saved spec path, registration date, and which is currently active.

---

switch-project

Switches the active API project. All subsequent tool calls will use the newly activated project's spec.

Argument	Type	Required	Description
projectName	string	Yes	The name of the project to activate (must already be registered)

Returns: Confirmation with the new active project's details.

Example:

Switch to project "medex"

---

available-api-endpoints

Lists all API endpoints grouped by OpenAPI tag.

Argument	Type	Required	Description
(none)	—	—	—

Returns: Endpoints grouped by tag with method and path, plus total count.

---

endpoint-detail

Returns the full contract for a specific endpoint: path/query/header parameters, request body schema (with $ref resolved), and all response schemas.

Argument	Type	Required	Description
path	string	Yes	API path, e.g. /users/{id}
method	string	No	HTTP method (GET, POST, etc.). If omitted, returns all methods for the path.

---

generate-curl

Generates a ready-to-run curl command for an endpoint. The sample request body is auto-generated from the schema (with placeholder values like "example@email.com", "uuid-here", etc.).

Argument	Type	Required	Description
path	string	Yes	API path
method	string	Yes	HTTP method
baseUrl	string	No	Override the base URL (defaults to the spec's server URL)
pathParams	object	No	Values for path parameters
queryParams	object	No	Values for query parameters
headers	object	No	Additional headers
body	object	No	Override the auto-generated request body

---

generate-typescript-types

Generates TypeScript interface or type definitions from an endpoint's schemas.

Argument	Type	Required	Description
path	string	Yes	API path
method	string	Yes	HTTP method
generate	array	Yes	Which parts to generate: "requestBody", "queryParams", "pathParams", "response"
outputStyle	string	Yes	"interface" or "type"
responseCodes	array	No	Specific response codes to include (e.g. ["200", "404"]). Defaults to all.

---

Available Prompts

Prompts are pre-built guided workflows that chain multiple tools together and provide context-aware instructions to the AI.

setup-project

Onboards a new API project. Guides you through calling generate-swagger-json and confirms the spec was loaded successfully.

Arguments: None

---

explore-api

Browse and summarize available API endpoints. Optionally filter by a specific tag.

Argument	Type	Required	Description
tag	string	No	Filter endpoints to a specific OpenAPI tag

---

implement-endpoint

Full implementation workflow for a single endpoint. Chains endpoint-detail → generate-curl → generate-typescript-types and presents everything needed to implement an API call.

Argument	Type	Required	Description
path	string	Yes	API path
method	string	Yes	HTTP method

---

generate-types

Generates TypeScript types with configurable options.

Argument	Type	Required	Description
path	string	Yes	API path
method	string	Yes	HTTP method
parts	array	No	Which parts to include (defaults to all)
style	string	No	"interface" or "type" (defaults to "interface")

---

test-endpoint

Generates a curl command and a Jest/Vitest test scaffold for an endpoint.

Argument	Type	Required	Description
path	string	Yes	API path
method	string	Yes	HTTP method

---

Typical Workflow

1. Initialize a project

Use the setup-project prompt

The AI will ask for your project name and Swagger JSON URL, then load and cache the spec.

1b. Register additional projects (optional)

Generate swagger JSON for projectName "payments-api" and swaggerUrl "https://pay.example.com/api-docs-json"

Each call to generate-swagger-json adds a new project without removing existing ones.

1c. Switch between projects

List all my registered projects

Switch to project "payments-api"

2. Explore the API

Use the explore-api prompt

Or filter by tag:

Use the explore-api prompt with tag "users"

3. Deep-dive into an endpoint

Use the implement-endpoint prompt with path "/auth/login" and method "POST"

This returns the full parameter/body/response contract, a sample curl command, and TypeScript types.

4. Generate types only

Use the generate-types prompt with path "/users/{id}" method "GET" style "interface"

5. Scaffold a test

Use the test-endpoint prompt with path "/auth/register" method "POST"

---

Project Structure

swagger/
├── src/
│   ├── server.ts                        # MCP server entry point (stdio transport)
│   ├── state/
│   │   └── project.state.ts             # In-memory + persisted project config
│   ├── types/
│   │   ├── index.ts                     # Tool / Prompt characteristic types
│   │   ├── endpoint.types.ts            # HTTP / endpoint domain types
│   │   └── openapi.types.ts             # OpenAPI spec types + type guard
│   ├── tools/
│   │   ├── generate-swagger-json.tool.ts
│   │   ├── list-projects.tool.ts
│   │   ├── switch-project.tool.ts
│   │   ├── available-endpoints.tool.ts
│   │   ├── endpoint-detail.tool.ts
│   │   ├── generate-curl.tool.ts
│   │   └── generate-typescript-types.tool.ts
│   ├── prompts/
│   │   ├── setup-project.prompt.ts
│   │   ├── explore-api.prompt.ts
│   │   ├── implement-endpoint.prompt.ts
│   │   ├── generate-types.prompt.ts
│   │   └── test-endpoint.prompt.ts
│   ├── helpers/
│   │   ├── endpoint-detail.helper.ts    # $ref resolution + endpoint parsing
│   │   ├── curl-builder.helper.ts       # curl command generation
│   │   └── typescript-type-builder.helper.ts  # JSON Schema → TypeScript
│   └── utility/
│       ├── add-tool-registry.utility.ts
│       ├── add-prompt-registry.utility.ts
│       └── swagger.utility.ts           # Fetch, save, load, parse OpenAPI specs
├── doc/
│   ├── .project-config.json             # Multi-project registry + active project pointer
│   └── *.json                           # Cached OpenAPI specs + grouped summaries (gitignored)
├── .env.sample                          # Environment variable template
├── package.json
└── tsconfig.json

---

Environment Variables

Copy .env.sample to .env. The variables are optional placeholders for future use — none are required for the server to run.

Variable	Description
CURSOR_API_KEY	Reserved for future Cursor integration
DEVELOPMENT_BASE_URL	Your API's development base URL
STAGING_BASE_URL	Your API's staging base URL
PRODUCTION_BASE_URL	Your API's production base URL
SWAGGER_TITLE	Default API title label
SWAGGER_VERSION	Default API version label
SWAGGER_DESCRIPTION	Default API description

---

Troubleshooting

The server doesn't appear in Cursor / Claude

• Verify the absolute paths in your MCP config are correct
• Confirm node_modules is installed (npm install)
• Check that Node.js is accessible at the command path — run which node to confirm
• Reload Cursor (Cmd+Shift+P → Developer: Reload Window) or restart Claude Desktop

generate-swagger-json returns an error about HTML

The swaggerUrl must point to the raw JSON spec, not the Swagger UI page. In Swagger UI, look for a link like /api-docs-json, /openapi.json, or /swagger.json — use that URL, not the browser page URL.

Tools return "No project configured"

Run generate-swagger-json first to initialize a project. Once registered, use list-projects to confirm it appears, and switch-project to activate it if needed.

Tools are querying the wrong API

You may have multiple projects registered. Call list-projects to check which project is currently active, then call switch-project with the correct name.

State is lost after restart

The server auto-restores state from doc/.project-config.json on startup. If this file is missing or corrupted, re-run generate-swagger-json.

MCP Inspector won't connect

Make sure you are not already running npm start in another terminal — only one process can hold stdio. Stop any running instance before launching the Inspector.

TypeScript types are missing fields

Deeply nested $ref schemas are resolved up to 10 levels deep to prevent circular reference loops. If a schema is cut off, it means the nesting exceeds this limit.