openapi

The openapi-mcp-server acts as a bridge between an OpenAPI/Swagger specification and the Model Context Protocol (MCP). It automatically converts each operation in your OpenAPI document into an MCP tool, allowing AI assistants to call API endpoints through the generated tools. The server supports OpenAPI v3.0.0 and v3.1.0 and includes authentication options such as Basic auth, Bearer tokens, and API keys, enabling secure access to your APIs. A crucial constraint is that every operation in the specification must have a unique and descriptive operationId; without this, the server will fail to start or function properly. To use the server, provide either a local OpenAPI file or a URL to your spec, and configure BASE_URL and HEADERS to control the target API endpoint and request customization. You can integrate the MCP tools into clients like Claude Desktop or Cursor by wiring the server as an MCP source using the provided command and environment variables. When running, each operationId from your API becomes the name of an MCP tool, making it easier for AI to discover and invoke the appropriate API calls.

Prerequisites:

• Node.js or Bun installed on your system (the project uses Bun in examples)
• Git
• Access to the repository you want to run (clone or download)

Install and run locally:

# Clone the repository
git clone https://github.com/sotayamashita/openapi-mcp-server.git
cd openapi-mcp-server

# Install dependencies (uses Bun in the project examples)
bun install

Usage example (local development):

# Start the server (example for a local OpenAPI file or URL)
bun run src/index.ts ./demo/openapi.yml

If you prefer using npm directly, install dependencies and run the TypeScript entry (adjust scripts as needed):

# Install dependencies
npm install

# Run the server (adjust path to index.ts and API spec as needed)
npm run --if-present build
node dist/index.js ./demo/openapi.yml

Configuration notes:

• The server reads environment variables like BASE_URL and HEADERS to control the target API and request defaults. See the README for details on configuring these values when integrating with clients like Claude Desktop or Cursor.

Tips and common considerations:

• Ensure every operation in your OpenAPI spec has a unique operationId to avoid startup/runtime failures.
• BASE_URL should point to your API host (the server URL or base path for the API).
• HEADERS can customize default request headers; provide valid JSON for the headers object.
• When integrating with Claude Desktop or Cursor, follow the examples in the README to wire the MCP server into the client configuration, including the command (bun), arguments (path to the server and the OpenAPI spec), and environment variables.
• If you update the OpenAPI spec, restart the MCP server to regenerate the tools based on the new operations.
• OpenAPI v2.0 is not supported, so migrate older specs to OpenAPI 3.x before using this server.