SwaggerToMCP

SwaggerToMCP is a command-line tool that converts OpenAPI/Swagger specifications into MCP context JSON, enabling Claude to interact with external APIs through a well-defined tool interface. The project focuses on retaining metadata from the input OpenAPI document and producing a valid MCP Tool object that mirrors operations, parameters, and security definitions. You can leverage this to automate tool generation from your API specs and integrate them into Claude-assisted workflows. The CLI accepts a Swagger/OpenAPI JSON file and outputs a single MCP-context JSON file that describes the available API operations as MCP tools.

Usage is straightforward: run the tool against your OpenAPI file to generate the MCP output, then supply that MCP-context to Claude as a tool configuration. The tool preserves complex constructs such as oneOf, anyOf, allOf, references ($ref), and extended JSON Schema features from OpenAPI 3.1.0, ensuring accurate modeling of APIs in MCP format.

Prerequisites:

• .NET 9.0 SDK or runtime installed on your system
• Git (optional, for cloning the repository)

Installation steps:

1. Clone the repository: git clone https://github.com/grparry/SwaggerToMCP.git
2. Navigate to the repository: cd SwaggerToMCP
3. Build the CLI project (requires the .NET SDK): dotnet build
4. Run the CLI against an OpenAPI/Swagger JSON file to generate MCP output: dotnet run --project SwaggerToMCP.Cli -- -i path/to/swagger.json -o path/to/mcp-context.json

Notes:

• The tool supports OpenAPI 2.0 (Swagger), 3.0, and 3.1.0 specifications, including complex schemas and discriminator handling.
• Ensure your OpenAPI document is accessible from the machine running the CLI (local path or URL).

Tips and common considerations:

• The output MCP file will map OpenAPI operations to MCP Tool objects; review the MCP-context.json to ensure all required fields align with your Claude integration needs.
• If your OpenAPI uses advanced JSON Schema features (oneOf/anyOf/allOf, $ref, discriminators), verify that the generated MCP retains these structures accurately.
• For large specifications, consider testing with a subset of endpoints to validate the conversion before running against the full document.
• Security definitions in OpenAPI (e.g., API keys, OAuth2) are preserved in the MCP output so Claude can authenticate when calling tools.
• If you encounter path or parameter translation issues, check the tool’s output logs for guidance on mapping adjustments or unsupported constructs.