Skip to content
openapi-mcp

Quickstart

Generate your first MCP server from an OpenAPI spec in a few minutes, run it locally and connect it to an MCP client.

By Updated

This guide takes you from an OpenAPI file to a running MCP server connected to a client.

1. Install#

Run the CLI with npx, no install needed:

bash
npx openapi-mcp-generator@5 --help

Or install it globally:

bash
npm install -g openapi-mcp-generator

You can also use yarn global add openapi-mcp-generator or pnpm add -g openapi-mcp-generator. The generator needs Node.js 22.19 or later; generated projects need Node.js 22 or later.

2. Generate a server#

Pass your spec with --input (a path or URL, JSON or YAML) and a target folder with --output:

bash
npx openapi-mcp-generator@5 --input ./openapi.json --output ./my-mcp

That produces a stdio server, which is the default and the best fit for local clients. To generate a deployable Cloudflare Worker instead:

bash
npx openapi-mcp-generator@5 --input ./openapi.json --output ./my-mcp --transport=cloudflare-worker

If your spec's servers list is missing or ambiguous, add --base-url https://api.example.com. Swagger 2.0 files are refused; convert them first with npx swagger2openapi swagger.json -o openapi.json.

3. Install and run#

bash
cd my-mcp
npm install
npm start

For web-based transports use npm run start:web (SSE) or npm run start:http (Streamable HTTP), then open http://localhost:3000/ to use the browser playground.

4. Add credentials#

If your API needs authentication, copy .env.example to .env and fill in the values. Variable names follow your spec's security scheme names, for example API_KEY_<SCHEME_NAME>. If a tool needs credentials that are not set, it returns an error naming the variable instead of calling your API. See Authentication.

5. Connect a client#

For a local stdio server, register the command with your client. With Claude Code:

bash
claude mcp add my-api -- node /absolute/path/to/my-mcp/build/index.js

build/index.js is the built entry file: the generated package.json sets "main" to it, and npm start runs node build/index.js.

See Connect clients for Cursor, VS Code, Claude.ai and the browser playground.

Next steps#

PreviousIntroductionNext CLI options