OpenAPI MCP Server

A Model Context Protocol (MCP) server for Claude/Cursor that enables searching and exploring OpenAPI specifications through oapis.org.

• Demo: https://x.com/janwilmake/status/1903497808134496583
• HN Thread: https://news.ycombinator.com/item?id=43447278
• OpenAPISearch: https://github.com/janwilmake/openapisearch
• OAPIS: https://github.com/janwilmake/oapis

The MCP works by applying a 2 step process :

2. It requests a summary of an openapi spec in simple language
3. It determines which endpoints you need, and checks out how exactly they work (again, in simple language)

Features

• Get an overview of any OpenAPI specification
• Retrieve details about specific API operations
• Support for both JSON and YAML formats
• Support for both stdio and HTTP server modes

Installation

Run and follow instructions:

npx openapi-mcp-server@latest init

Usage in Claude

Once installed, you can ask Claude to:

• "Find information about the Stripe API"
• "Explain how to use the GitHub API's repository endpoints"

Claude will use the MCP server to:

1. First get an overview of the requested API
2. Then retrieve specific operation details as needed

Requirements

• Node.js >= 22.0.0
• Claude Desktop, Cursor, or any other MCP client.

Running the Server

The server can be run in two different modes:

stdio Mode (Default)

This is the default mode and is used when integrating with Claude Desktop or other MCP clients that launch the server as a subprocess:

node dist/index.js
# or
node dist/index.js stdio

HTTP Mode

This mode starts an HTTP server that implements the Streamable HTTP transport protocol for MCP. This is useful for remote clients or when you want to run the server as a standalone service:

node dist/index.js http [port]

The default port is 3000 if not specified.

Running with Docker

You can also build and run the server using Docker.

Build the Image

From the project root directory, run:

docker build -t openapi-dig-mcp .

Run the Container

stdio Mode (Default)

To run the container in the default stdio mode:

docker run --rm -i openapi-dig-mcp

HTTP Mode

To run the container in HTTP mode, exposing the server on port 3000:

docker run --rm -p 3000:3000 openapi-dig-mcp http 3000

You can replace 3000 with a different port if needed, both in the -p mapping and the command argument.

Development

This project uses a modern TypeScript setup with ESLint and Prettier for code quality.

Setup

# Install dependencies
yarn install

# Start development mode with watch
yarn dev

Available Scripts

• yarn build - Build the project
• yarn dev - Start development mode with watch
• yarn lint - Run ESLint
• yarn lint:fix - Run ESLint with auto-fix
• yarn format - Format code with Prettier
• yarn check-types - Check TypeScript types
• yarn start - Run the compiled application

License

MIT