yutashx/openapi-mcp-server

OpenAPI MCP Server

This project generates a Model Context Protocol (MCP) server from an OpenAPI (v3) specification file. It allows AI models like Claude to interact with the defined API endpoints through MCP tools. All source code is generated by Cline and gemini-2.5-pro using

Requirements

• Bun

Installation

1. Clone or download this project.
2. Navigate to the project directory:

   cd openapi-mcp-server
   

3. Install dependencies:

   bun install
   

Building

To compile the TypeScript code into executable JavaScript, targeting the Bun runtime (necessary because dependencies like node-fetch use Node.js APIs):

bun build ./src/index.ts --outdir ./dist --target=bun

This will create the output file(s) in the dist directory, correctly bundled for the Bun environment.

Running Manually (for Testing/Debugging)

You can run the compiled server directly from your terminal. This is useful for testing the parsing and basic functionality, but it won't connect to an MCP client unless configured.

bun run ./dist/index.js <path-to-openapi-spec> [optional-base-url]

Arguments:

• <path-to-openapi-spec>: (Required) The absolute or relative path to your OpenAPI specification file (JSON or YAML).
• [optional-base-url]: (Optional) A base URL to override the servers[0].url defined in the OpenAPI specification. If omitted and no server URL is found in the spec, the server will exit with an error.

Example:

# Using the included sample spec
bun run ./dist/index.js ./openapi.yaml

# Using a different spec and overriding the base URL
bun run ./dist/index.js /path/to/my/api.json https://my-api.example.com/v2

The server will print logs to stderr and listen for MCP communication on stdin/stdout. Press Ctrl+C to stop it.

Configuring as an MCP Server (e.g., for Claude Desktop / VS Code Extension)

To make this server available to an MCP client like the Claude VS Code extension, add its configuration to the appropriate settings file.

Example cline_mcp_settings.json (VS Code):

Location may vary, e.g., ~/Library/Application Support/Code/User/globalStorage/saoudrizwan.claude-dev/settings/cline_mcp_settings.json on macOS.

{
  "mcpServers": {
    "my-custom-api": { // Choose a unique name for your server
      "command": "bun",
      "args": [
        "run",
        // Use the *absolute path* to the compiled index.js
        "/path/to/your/openapi-mcp-server/dist/index.js",
        // Use the *absolute path* to your OpenAPI spec
        "/path/to/your/openapi-mcp-server/openapi.yaml"
        // Add the base URL override here if needed
        // "https://override-base-url.com"
      ],
      "env": {
        // Add any necessary environment variables here (e.g., API keys)
        // "API_KEY": "your-secret-key"
      },
      "disabled": false, // Set to true to temporarily disable
      "autoApprove": [] // List tool names to auto-approve if desired
    }
    // ... other servers
  }
}

Important:

• Replace /path/to/your/openapi-mcp-server/ with the actual absolute path to this project directory on your system.
• Ensure the paths to dist/index.js and your OpenAPI spec file are correct absolute paths.
• The MCP client (VS Code extension, etc.) will automatically start and manage the server process based on this configuration. You do not need to run it manually when using it via MCP.

Once configured, the client will connect to the server, and you can use the generated tools (like listPets, showPetById from the sample spec) by asking the AI to perform the corresponding actions.