openapi-to-mcp

English | Türkçe

Turn an OpenAPI 3.0/3.1 document into MCP tools, a stdio server, or a standalone server project. Local spec loading, typed library APIs and read-only defaults, with just two direct runtime dependencies. Install from this checkout with Node 24: npm ci && npm run build. Try it: node dist/bin.js list examples/petstore.yaml.

Demo

node dist/bin.js list examples/petstore.yaml
node dist/bin.js list examples/petstore.yaml --include 'tag:pets'
node examples/call-tool.mjs

The first command prints:

listPets        GET    /pets
getPet          GET    /pets/{petId}
listOwnerPets   GET    /owners/{ownerId}/pets
listCategories  GET    /categories
get_health      GET    /health

5 tools, 4 skipped (4 write-disabled)

The last command starts a synthetic loopback API, connects an MCP client to the CLI, calls getPet, and shows that createPet is unavailable. It needs no API account or credentials. Regenerate the terminal image with npm run demo using scripts/make-demo.mjs.

Related MCP server: HiMCP

Install

Use the source checkout: npm ci && npm run build. Development tools require Node 22.13+ or 24+; the compiled CLI and library support Node 20+. CI checks the toolchain on Node 22/24 and runtime compatibility on Node 20.

The npm name openapi-to-mcp may refer to an unrelated project; registry ownership has not been verified for this checkout. The npm badge describes that registry name, not a release of this code. Use the local build until the maintainer resolves the package name. No global installation is required.

Usage

CLI

node dist/bin.js --help
node dist/bin.js list examples/petstore.yaml --allow-write --exclude 'tag:admin'
node dist/bin.js generate examples/petstore.yaml -o is/petstore-mcp

list previews tools without making API requests or reading authentication variables. generate writes six files: server.mjs, runtime.js, mcp.js, tools.json, package.json, and a README. It refuses to replace any existing generated file; use a fresh directory for a new export. Generated projects contain the manifest and runtime, and need only the MCP SDK at runtime.

To start a generated server, install its dependencies in that output directory and launch server.mjs with Node. A stdio server waits for an MCP client and reserves stdout for protocol messages; diagnostics go to stderr.

An MCP client's stdio configuration can point directly to the built CLI:

{
  "mcpServers": {
    "petstore": {
      "command": "node",
      "args": ["dist/bin.js", "serve", "examples/petstore.yaml"]
    }
  }
}

Resolve these relative paths from the checkout's working directory, or configure the client with paths appropriate to your installation. The example spec's server is a placeholder; use --base-url for a real API. GET and HEAD are exposed by default; other supported methods require --allow-write.

Library

import { loadSpec, buildManifest, createExecutor } from './dist/index.js';

const spec = await loadSpec('examples/petstore.yaml');
const { manifest, skipped } = buildManifest(spec, { include: ['getPet'] });
console.log(manifest.tools.map((tool) => tool.name), skipped.length);
const executor = createExecutor(manifest, {
  env: {},
  fetch: async () => new Response('{"id":1,"name":"Rex"}', {
    headers: { 'Content-Type': 'application/json' },
  }),
});
console.log((await executor.execute('getPet', { petId: 1 })).text);

The injected fetch above keeps the example offline. See examples/library.mjs for this runnable example. Without an injected fetch, execute sends an HTTP request. It returns { isError, text }; HTTP 4xx/5xx, timeouts and request failures become tool errors.

The package root exports parseSpec, loadSpec, resolveBaseUrl, buildManifest, matchesPattern, deref, convertSchema, createExecutor, createMcpServer, and generateProject, along with their public types. createMcpServer(manifest, deps?, info?) returns an unconnected SDK server; connect it to a transport. generateProject(manifest, outDir, options?) returns the names of the files it writes.

Examples

• petstore.yaml: OpenAPI 3.0 with local references, recursive schemas, filters, JSON bodies and form bodies.

• call-tool.mjs: an actual stdio MCP client and local fake HTTP API.

• library.mjs: the library API with an injected response and no network access. Run node examples/library.mjs after building.

• mini31.json: OpenAPI 3.1, nullable unions, colliding names and unsupported uploads.

Configuration

Patterns match the tool name, original operationId, tag:NAME, or METHOD /path. Matching is case-insensitive and anchored; * matches any sequence and ? one character. Quote patterns so your shell passes them unchanged.

OPENAPI_MCP_BASE_URL overrides the base URL when the executor starts, including in generated servers. Its host must be allowed. A host entry without a port allows any port on that hostname; specify hostname:port to restrict it. Redirects are returned without being followed. Base URLs must use HTTP(S) and contain no credentials, query string or fragment.

Authentication values belong in the process environment supplied by your MCP client. Flags and generated manifests store variable names, never token values. Authorization and Cookie are hidden from tool arguments, as are all headers configured with headerEnv. Explicitly configure custom authentication headers such as X-Api-Key; OpenAPI securitySchemes are not wired automatically. Missing authentication variables fail at server startup.

How it works

1. Parse a local JSON or YAML file and resolve local JSON pointers. Recursive references become an open placeholder schema; expansion has a node budget.

2. Select operations, merge path and operation parameters, assign unique names, and convert OpenAPI schema keywords into JSON Schema.

3. Expose input schemas through the official MCP SDK. Each call serializes path, query, header and JSON/form body values into a bounded HTTP request.

Limitations and privacy

Supported versions are OpenAPI 3.0.x and 3.1.x. Supported methods are GET, HEAD, POST, PUT, PATCH, DELETE and OPTIONS. Only top-level server selection is supported. Remote references, Swagger 2, callbacks, links, cookies as parameters, multipart/binary uploads and OAuth flows are not implemented. JSON and application/*+json body media types are preserved; form-urlencoded bodies are supported.

Parameter serialization supports simple paths, form queries, flat deepObject queries, space/pipe-delimited arrays and header values. Matrix/label path styles, nested deep objects and parameter content encodings are not fully implemented. Recursive schema placeholders lose recursive constraints. Schemas are advertised to clients; the executor checks required arguments but does not perform full JSON Schema validation or insert schema defaults.

Spec parsing, listing and generation are local. Serving sends supplied arguments and configured credentials to your chosen API, and returns its response to the MCP client. Review specs, destinations and client permissions before connecting sensitive data. API responses can contain secrets or malicious instructions; they are passed through as text without redaction. A host allowlist is not DNS or IP isolation, and a GET endpoint can still have side effects. Generated manifests contain the selected API URL, paths and schema descriptions; review them before sharing.

Development

Use Node 24 and the existing lockfile:

npm run lint
npm run typecheck
npm test
npm run build
npm pack --dry-run --cache ./is/npm-cache

Run npm ci first when dependencies are absent. npm test builds and runs Vitest with V8 coverage. The enforced thresholds are 85% for statements, branches, functions and lines. Tests use synthetic data, injected fetch implementations or loopback HTTP servers; no external API is required. End-to-end tests exercise stdio and generated projects. CI runs on Ubuntu and Windows. src/bin.ts is exercised by the stdio tests but excluded from Vitest's in-process coverage report.

Contributing

See CONTRIBUTING.md, CHANGELOG.md, SECURITY.md, and the Code of Conduct. GitHub workflows cover CI, CodeQL, weekly dependency updates and tag-triggered publishing. A maintainer must configure npm trusted publishing and resolve the package name before a release.

License

MIT, copyright 2026 Yusuf Berat Zengin.