@avidian/mcp-openapi

MCP server for OpenAPI/Swagger — gives AI agents the ability to discover, search, and call any REST API described by an OpenAPI or Swagger document.

Point it at a single OpenAPI/Swagger document (URL or local file, 2.0/3.0/3.1) and it exposes:

• The full, dereferenced document as a readable MCP resource
• A keyword search tool for finding the right operation when a spec defines many of them
• One MCP tool per operation, which proxies a real HTTP request to the underlying API

Installation

npm (requires Node.js ≥ 20)

npm install -g @avidian/mcp-openapi

Compiled binary (no runtime needed)

Download from GitHub Releases.

Usage

mcp-openapi <openapi-url-or-path> [--base-url <url>] [--timeout <ms>]

mcp-openapi https://petstore3.swagger.io/api/v3/openapi.json
mcp-openapi ./openapi.yaml --base-url https://api.internal.example.com --timeout 10000

The source may also come from OPENAPI_URL instead of the positional argument, which is convenient for MCP client configs.

MCP client configuration

{
  "mcpServers": {
    "my-api": {
      "command": "mcp-openapi",
      "args": ["https://api.example.com/openapi.json"]
    }
  }
}

Configuration

| Variable | Description | | ---------------------------- | ----------------------------------------------------------------------------- | | OPENAPI_URL | OpenAPI/Swagger source (URL or local path), if not passed as the CLI argument | | OPENAPI_BASE_URL | Overrides every server URL declared in the spec | | OPENAPI_REQUEST_TIMEOUT_MS | Per-request timeout in milliseconds (default 30000) |

Authentication

For each security scheme declared in the OpenAPI document, credentials are read from environment variables named after the scheme (converted to SCREAMING_SNAKE_CASE) — e.g. a scheme called apiKeyAuth reads OPENAPI_AUTH_API_KEY_AUTH.

| Scheme type | Environment variables | | ------------------------------ | --------------------------------------------------------------------- | | HTTP bearer | OPENAPI_AUTH_<SCHEME>_TOKEN (or bare OPENAPI_AUTH_<SCHEME>) | | HTTP basic | OPENAPI_AUTH_<SCHEME>_USERNAME and OPENAPI_AUTH_<SCHEME>_PASSWORD | | apiKey (header, query, cookie) | OPENAPI_AUTH_<SCHEME> |

Schemes with no matching environment variable, and unsupported types (OAuth2, OpenID Connect), are skipped with a warning rather than failing startup.

What it exposes

• Resource openapi://spec — the full, dereferenced OpenAPI/Swagger document.
• Tool search_operations — keyword search across every operation's name, summary, description, tags, and path. Use this first when a spec defines many operations.
• One tool per operation — named after its operationId (sanitized and deduplicated), taking the operation's path/query/header parameters and request body as arguments.

Development

# Install dependencies
bun install

# Run in dev mode
bun run dev <openapi-url-or-path>

# Type check
bun run typecheck

# Lint
bun run lint

# Format
bun run format

# Test
bun run test

# Build for npm
bun run build

# Compile native binary
bun run compile

ajv is listed as a direct devDependency even though nothing in src/ imports it. It's a workaround: @apidevtools/swagger-parser depends on ajv-draft-04, which only declares ajv as a peer dependency, and Bun's bundler fails to statically resolve that peer dependency when producing standalone binaries (bun run compile) unless ajv is also resolvable as a direct dependency somewhere in the root of the tree. Not needed for bun run build (the npm-published bundle), which keeps @apidevtools/swagger-parser external and lets Node resolve it normally at install time.

License

MIT