oguzhan2142/SwaggerMcpServer

Swagger MCP Server

A Model Context Protocol (MCP) server that loads an OpenAPI (Swagger) document and exposes tools to explore operations and component schemas. It runs over stdio (no network port) so MCP-enabled clients can spawn it directly.

Features

• Preloads an OpenAPI document on startup (URL or file path)
• List operations (with optional tag and free-text filters)
• Get operation details (parameters, request body, responses)
• List component schemas and fetch a schema by name

Requirements

• .NET SDK 9.0+
• Optional: Docker (for containerized runs)

Configure the OpenAPI source

The server reads the OpenAPI source from either:

• Environment variable: OPENAPI_URL, or
• Command-line arg: --openapi=<url-or-path>

If neither is provided, it defaults to:

http://localhost:4000/swagger/Admin/swagger.json

Build and Run (local)

From the project root:

# Build
dotnet build -c Release

# Run with a URL
OPENAPI_URL="http://localhost:4000/swagger/Admin/swagger.json" \
  dotnet run -c Release --

# Or run with a file path
dotnet run -c Release -- --openapi="/absolute/path/to/openapi.json"

Note: The process is an MCP server over stdio; integrate by configuring your MCP client to launch this command.

Docker

Build a small runtime image using the provided multi-stage Dockerfile:

# Build the image
docker build -t swagger-mcp-server:dev .

# Run with a URL (on macOS, access the host service via host.docker.internal)
docker run --rm -i \
  -e OPENAPI_URL="http://host.docker.internal:4000/swagger/Admin/swagger.json" \
  swagger-mcp-server:dev

MCP Tools exposed

All tool responses are JSON strings for clarity.

• reload_openapi(source: string)

  • Description: Reload the OpenAPI document from a URL or file path.
  • Returns: { ok: boolean, loadedAt: string, source: string }

• list_openapi_operations(tag?: string, search?: string)

  • Description: List operations, optionally filtered by tag and free-text search.
  • Returns: { count: number, operations: OperationInfo[] }

• get_operation_details(operationId?: string, method?: string, path?: string)

  • Description: Get method, path, parameters, request body, and responses for an operation.
  • Contract: Provide either operationId OR both method and path.
  • Returns: OperationDetails

• list_component_schemas()

  • Description: List component schema names.
  • Returns: { count: number, names: string[] }

• get_component_schema(name: string)

  • Description: Return the raw OpenAPI v3 JSON for a component schema by name.
  • Returns: { name: string, schema: object }

Typical client integration

Configure your MCP client to launch the server command (stdio). Example command:

# URL-based
OPENAPI_URL="https://your.api/swagger/v1/swagger.json" \
  dotnet /path/to/bin/Release/net9.0/SwaggerMcpServer.dll

# CLI-arg based
/path/to/bin/Release/net9.0/SwaggerMcpServer.dll --openapi="/path/to/openapi.json"

VS Code MCP setup (mcp.json)

To use this server from a VS Code MCP-enabled client, add the following entry to your mcp.json:

{
  "swagger-introspector": {
    "command": "dotnet",
    "args": [
      "run",
      "--project",
      "/Users/oguzhan/Developer/Personal/SwaggerMcpServer/SwaggerMcpServer.csproj"
    ],
    "env": {
      "OPENAPI_URL": "http://localhost:4000/swagger/Admin/swagger.json"
    }
  }
}

Notes:

• Keep the --project path pointing to your SwaggerMcpServer.csproj.
• You can change OPENAPI_URL to any URL or file path. If you omit it, the default in Program.cs will be used.

Troubleshooting

• "Got HTML instead of OpenAPI JSON/YAML": ensure the URL points to the raw JSON/YAML (e.g., .../swagger/v1/swagger.json), not the Swagger UI page or an auth error page.
• Empty content: verify the target returns the document, not an empty response.
• Preload fails: you can still start the server and call reload_openapi later to load a different source.

Project structure (high level)

• Program.cs: Host setup, DI, and MCP stdio server
• Services/OpenApiService.cs: Loads and indexes the OpenAPI doc
• Services/OpenApiPreloader.cs: Loads the doc on startup
• Utilities/SwaggerTools.cs: MCP tools exposed to clients

License

MIT License. See .