OpenAPI

by ivo-toby

62 16.9k downloads Not rated yet MIT

GitHub Website

About

Integrates with OpenAPI specifications to expose REST API endpoints as MCP resources, enabling dynamic discovery and utilization of many web services.

Details

Repository: ivo-toby/mcp-openapi-server
License: MIT

Explore

- Exposes OpenAPI endpoints as MCP tools automatically
- Supports loading OpenAPI specs via URL, file, stdin, or inline
- Two transports: stdio (default) and Streamable HTTP
- Mutual TLS (mTLS) support for upstream API authentication
- Tool loading modes: all, dynamic, or explicit
- Filtering by tags and custom headers

Setting up with Highlight

This MCP is not yet compatible with Highlight’s one-click setup. However, you can still use it with Highlight by following these steps:

Download and install Highlight from highlightai.com/download
Navigate to the plugins tab and select "Add Custom Plugin"
Configure the plugin with the settings below
Plugin Name OpenAPI

Command (node, npx, python, etc.) npx
Arguments
- Argument 1 -y
- Argument 2 @ivotoby/openapi-mcp-server
Environment
- API_HEADERS Authorization:Bearer token123,X-API-Key:your-api-key
- API_BASE_URL https://api.example.com
- OPENAPI_SPEC_PATH https://api.example.com/openapi.json
Please refer to the README for specific instructions on how to obtain API keys or other required environment variables.
Enable "Start Automatically" if you want the plugin to start when Highlight launches

Setting up with Cursor

Open Cursor's settings
Navigate to the MCP section
Click "Add new Global MCP server"
Copy and paste the configuration below based on your operating system

JSON

{
    "mcpServers": {
        "openapi": {
            "env": {
                "API_HEADERS": "Authorization:Bearer token123,X-API-Key:your-api-key",
                "API_BASE_URL": "https://api.example.com",
                "OPENAPI_SPEC_PATH": "https://api.example.com/openapi.json"
            },
            "args": [
                "-y",
                "@ivotoby/openapi-mcp-server"
            ],
            "command": "npx"
        }
    }
}

JSON

{
    "mcpServers": {
        "openapi": {
            "env": {
                "API_HEADERS": "Authorization:Bearer token123,X-API-Key:your-api-key",
                "API_BASE_URL": "https://api.example.com",
                "OPENAPI_SPEC_PATH": "https://api.example.com/openapi.json"
            },
            "args": [
                "/c",
                "npx",
                "-y",
                "@ivotoby/openapi-mcp-server"
            ],
            "command": "cmd"
        }
    }
}

JSON

{
    "mcpServers": {
        "openapi": {
            "env": {
                "API_HEADERS": "Authorization:Bearer token123,X-API-Key:your-api-key",
                "API_BASE_URL": "https://api.example.com",
                "OPENAPI_SPEC_PATH": "https://api.example.com/openapi.json"
            },
            "args": [
                "-y",
                "@ivotoby/openapi-mcp-server"
            ],
            "command": "npx"
        }
    }
}

Setting up with Claude Desktop

Open Claude Desktop's settings
Go to the Integrations tab
Click "Add MCP Server"
Use the configuration below based on your operating system

Note: Make sure Claude Desktop is running before attempting to connect.

JSON

{
    "mcpServers": {
        "openapi": {
            "env": {
                "API_HEADERS": "Authorization:Bearer token123,X-API-Key:your-api-key",
                "API_BASE_URL": "https://api.example.com",
                "OPENAPI_SPEC_PATH": "https://api.example.com/openapi.json"
            },
            "args": [
                "-y",
                "@ivotoby/openapi-mcp-server"
            ],
            "command": "npx"
        }
    }
}

JSON

{
    "mcpServers": {
        "openapi": {
            "env": {
                "API_HEADERS": "Authorization:Bearer token123,X-API-Key:your-api-key",
                "API_BASE_URL": "https://api.example.com",
                "OPENAPI_SPEC_PATH": "https://api.example.com/openapi.json"
            },
            "args": [
                "/c",
                "npx",
                "-y",
                "@ivotoby/openapi-mcp-server"
            ],
            "command": "cmd"
        }
    }
}

JSON

{
    "mcpServers": {
        "openapi": {
            "env": {
                "API_HEADERS": "Authorization:Bearer token123,X-API-Key:your-api-key",
                "API_BASE_URL": "https://api.example.com",
                "OPENAPI_SPEC_PATH": "https://api.example.com/openapi.json"
            },
            "args": [
                "-y",
                "@ivotoby/openapi-mcp-server"
            ],
            "command": "npx"
        }
    }
}

Setting up with Windsurf

Open Windsurf's preferences
Go to the Integrations section
Click "Add MCP Integration"
Use the configuration below based on your operating system

JSON

{
    "mcpServers": {
        "openapi": {
            "env": {
                "API_HEADERS": "Authorization:Bearer token123,X-API-Key:your-api-key",
                "API_BASE_URL": "https://api.example.com",
                "OPENAPI_SPEC_PATH": "https://api.example.com/openapi.json"
            },
            "args": [
                "-y",
                "@ivotoby/openapi-mcp-server"
            ],
            "command": "npx"
        }
    }
}

JSON

{
    "mcpServers": {
        "openapi": {
            "env": {
                "API_HEADERS": "Authorization:Bearer token123,X-API-Key:your-api-key",
                "API_BASE_URL": "https://api.example.com",
                "OPENAPI_SPEC_PATH": "https://api.example.com/openapi.json"
            },
            "args": [
                "/c",
                "npx",
                "-y",
                "@ivotoby/openapi-mcp-server"
            ],
            "command": "cmd"
        }
    }
}

JSON

{
    "mcpServers": {
        "openapi": {
            "env": {
                "API_HEADERS": "Authorization:Bearer token123,X-API-Key:your-api-key",
                "API_BASE_URL": "https://api.example.com",
                "OPENAPI_SPEC_PATH": "https://api.example.com/openapi.json"
            },
            "args": [
                "-y",
                "@ivotoby/openapi-mcp-server"
            ],
            "command": "npx"
        }
    }
}

Setting up with Cline

Open Cline's settings
Navigate to the Integrations section
Click "Add MCP Server"
Copy and paste the configuration below based on your operating system

Note: Make sure to restart Cline after adding the configuration.

JSON

{
    "mcpServers": {
        "openapi": {
            "env": {
                "API_HEADERS": "Authorization:Bearer token123,X-API-Key:your-api-key",
                "API_BASE_URL": "https://api.example.com",
                "OPENAPI_SPEC_PATH": "https://api.example.com/openapi.json"
            },
            "args": [
                "-y",
                "@ivotoby/openapi-mcp-server"
            ],
            "command": "npx"
        }
    }
}

JSON

{
    "mcpServers": {
        "openapi": {
            "env": {
                "API_HEADERS": "Authorization:Bearer token123,X-API-Key:your-api-key",
                "API_BASE_URL": "https://api.example.com",
                "OPENAPI_SPEC_PATH": "https://api.example.com/openapi.json"
            },
            "args": [
                "/c",
                "npx",
                "-y",
                "@ivotoby/openapi-mcp-server"
            ],
            "command": "cmd"
        }
    }
}

JSON

{
    "mcpServers": {
        "openapi": {
            "env": {
                "API_HEADERS": "Authorization:Bearer token123,X-API-Key:your-api-key",
                "API_BASE_URL": "https://api.example.com",
                "OPENAPI_SPEC_PATH": "https://api.example.com/openapi.json"
            },
            "args": [
                "-y",
                "@ivotoby/openapi-mcp-server"
            ],
            "command": "npx"
        }
    }
}

Setting up with Goose

Open Goose's preferences
Go to the Integrations tab
Select "MCP Servers"
Click "Add New Server"
Use the configuration below based on your operating system

JSON

{
    "mcpServers": {
        "openapi": {
            "env": {
                "API_HEADERS": "Authorization:Bearer token123,X-API-Key:your-api-key",
                "API_BASE_URL": "https://api.example.com",
                "OPENAPI_SPEC_PATH": "https://api.example.com/openapi.json"
            },
            "args": [
                "-y",
                "@ivotoby/openapi-mcp-server"
            ],
            "command": "npx"
        }
    }
}

JSON

{
    "mcpServers": {
        "openapi": {
            "env": {
                "API_HEADERS": "Authorization:Bearer token123,X-API-Key:your-api-key",
                "API_BASE_URL": "https://api.example.com",
                "OPENAPI_SPEC_PATH": "https://api.example.com/openapi.json"
            },
            "args": [
                "/c",
                "npx",
                "-y",
                "@ivotoby/openapi-mcp-server"
            ],
            "command": "cmd"
        }
    }
}

JSON

{
    "mcpServers": {
        "openapi": {
            "env": {
                "API_HEADERS": "Authorization:Bearer token123,X-API-Key:your-api-key",
                "API_BASE_URL": "https://api.example.com",
                "OPENAPI_SPEC_PATH": "https://api.example.com/openapi.json"
            },
            "args": [
                "-y",
                "@ivotoby/openapi-mcp-server"
            ],
            "command": "npx"
        }
    }
}

From the repository

The server can be configured through environment variables or command line arguments:

- API_BASE_URL - Base URL for the API endpoints
- OPENAPI_SPEC_PATH - Path or URL to OpenAPI specification
- OPENAPI_SPEC_FROM_STDIN - Set to "true" to read OpenAPI spec from standard input
- OPENAPI_SPEC_INLINE - Provide OpenAPI spec content directly as a string
- API_HEADERS - Comma-separated key:value pairs for API headers
- CLIENT_CERT_PATH - Path to client certificate PEM file for mutual TLS
- CLIENT_KEY_PATH - Path to client private key PEM file for mutual TLS
- CA_CERT_PATH - Path to custom CA certificate PEM file for private/internal CAs
- CLIENT_KEY_PASSPHRASE - Passphrase for an encrypted client private key
- REJECT_UNAUTHORIZED - Whether to reject untrusted server certificates (default: true)
- SERVER_NAME - Name for the MCP server (default: "mcp-openapi-server")
- SERVER_VERSION - Version of the server (default: "1.0.0")
- TRANSPORT_TYPE - Transport type to use: "stdio" or "http" (default: "stdio")
- HTTP_PORT - Port for HTTP transport (default: 3000)
- HTTP_HOST - Host for HTTP transport (default: "127.0.0.1")
- ENDPOINT_PATH - Endpoint path for HTTP transport (default: "/mcp")
- TOOLS_MODE - Tools loading mode: "all" (load all endpoint-based tools), "dynamic" (load only meta-tools), or "explicit" (load only tools specified in includeTools) (default: "all")
- DISABLE_ABBREVIATION - Disable name optimization (this could throw errors when name is > 64 chars)
- VERBOSE - Enable operational logging (true by default; set to false to suppress non-essential logs)
- PROMPTS_PATH - Path or URL to prompts JSON/YAML file
- PROMPTS_INLINE - Provide prompts directly as JSON string
- RESOURCES_PATH - Path or URL to resources JSON/YAML file
- RESOURCES_INLINE - Provide resources directly as JSON string

export OPENAPI_SPEC_FROM_STDIN=true
echo '{"openapi": "3.0.0", ...}' | npx @ivotoby/openapi-mcp-server \
--api-base-url https://api.example.com

For containerized deployments, you can mount OpenAPI specs or use stdin:

bash

`all`

(default): Load all tools from the OpenAPI spec, applying any specified filters

`dynamic`

Load only dynamic meta-tools (`list-api-endpoints`, `get-api-endpoint-schema`, `invoke-api-endpoint`). `--exclude-tag` still applies to dynamic endpoint discovery and invocation.

`explicit`

Load only tools explicitly listed in `--tool` options, ignoring include filters. `--exclude-tag` still applies as a deny filter.

Based on the Stainless article "What We Learned Converting Complex OpenAPI Specs to MCP Servers" (https://www.stainless.com/blog/what-we-learned-converting-complex-openapi-specs-to-mcp-servers), the following flags were added to control which API endpoints (tools) are loaded:

- --tools <all|dynamic|explicit>: Choose tool loading mode:
- all (default): Load all tools from the OpenAPI spec, applying any specified filters
- dynamic: Load only dynamic meta-tools (list-api-endpoints, get-api-endpoint-schema, invoke-api-endpoint). --exclude-tag still applies to dynamic endpoint discovery and invocation.
- explicit: Load only tools explicitly listed in --tool options, ignoring include filters. --exclude-tag still applies as a deny filter.
- --tool <toolId>: Import only specified tool IDs or names. Can be used multiple times. In all mode, this bypasses --tag, --resource, and --operation, but not --exclude-tag.
- --tag <tag>: Import only tools with the specified OpenAPI tag. Can be used multiple times.
- --exclude-tag <tag>: Exclude tools with the specified OpenAPI tag. Can be used multiple times. Excluded tags take precedence over --tool.
- --resource <resource>: Import only tools under the specified resource path prefixes. Can be used multiple times.
- --operation <method>: Import only tools for the specified HTTP methods (get, post, etc). Can be used multiple times.

Tag filters are tool-surface controls, not authorization. Keep protecting sensitive endpoints with the upstream API's auth model. Untagged endpoints are not affected by --exclude-tag.

Examples:

npx @ivotoby/openapi-mcp-server --api-base-url https://api.example.com --openapi-spec https://api.example.com/openapi.json --tools dynamic npx @ivotoby/openapi-mcp-server --api-base-url https://api.example.com --openapi-spec https://api.example.com/openapi.json --tools explicit --tool GET::users --tool POST::users npx @ivotoby/openapi-mcp-server --api-base-url https://api.example.com --openapi-spec https://api.example.com/openapi.json --tool GET-users npx @ivotoby/openapi-mcp-server --api-base-url https://api.example.com --openapi-spec https://api.example.com/openapi.json --tag user --resource users npx @ivotoby/openapi-mcp-server --api-base-url https://api.example.com --openapi-spec https://api.example.com/openapi.json --exclude-tag admin --exclude-tag internal

bash
npx @ivotoby/openapi-mcp-server \
--api-base-url https://api.example.com \
--openapi-spec https://api.example.com/openapi.json \
--prompts ./prompts.json \
--mcp-resources ./resources.json \
--transport http \
--port 3000

With this configuration, the server advertises capabilities for all three:

json
{
"capabilities": {
"tools": { "list": true, "execute": true },
"prompts": {},
"resources": {}
}
}
```

Claude Desktop / Cursor

Paste into your MCP client config file to install this server.

{
    "mcpServers": {
        "openapi": {
            "env": {
                "API_HEADERS": "Authorization:Bearer token123,X-API-Key:your-api-key",
                "API_BASE_URL": "https://api.example.com",
                "OPENAPI_SPEC_PATH": "https://api.example.com/openapi.json"
            },
            "args": [
                "-y",
                "@ivotoby/openapi-mcp-server"
            ],
            "command": "npx"
        }
    }
}

Linux

{
    "env": {
        "API_HEADERS": "Authorization:Bearer token123,X-API-Key:your-api-key",
        "API_BASE_URL": "https://api.example.com",
        "OPENAPI_SPEC_PATH": "https://api.example.com/openapi.json"
    },
    "args": [
        "-y",
        "@ivotoby/openapi-mcp-server"
    ],
    "command": "npx"
}

Macos

{
    "env": {
        "API_HEADERS": "Authorization:Bearer token123,X-API-Key:your-api-key",
        "API_BASE_URL": "https://api.example.com",
        "OPENAPI_SPEC_PATH": "https://api.example.com/openapi.json"
    },
    "args": [
        "-y",
        "@ivotoby/openapi-mcp-server"
    ],
    "command": "npx"
}

Windows

{
    "env": {
        "API_HEADERS": "Authorization:Bearer token123,X-API-Key:your-api-key",
        "API_BASE_URL": "https://api.example.com",
        "OPENAPI_SPEC_PATH": "https://api.example.com/openapi.json"
    },
    "args": [
        "/c",
        "npx",
        "-y",
        "@ivotoby/openapi-mcp-server"
    ],
    "command": "cmd"
}

A Model Context Protocol (MCP) server that exposes OpenAPI endpoints as MCP tools, along with optional support for MCP prompts and resources. This server allows Large Language Models to discover and interact with REST APIs defined by OpenAPI specifications through the MCP protocol.

📖 Documentation

- User Guide - For users wanting to use this MCP server with Claude Desktop, Cursor, or other MCP clients
- Library Usage - For developers creating custom MCP servers using this package as a library
- Developer Guide - For contributors and developers working on the codebase
- AuthProvider Guide - Detailed authentication patterns and examples

---

No reviews yet — be the first

Use Google, GitHub, or an email account so ratings stay tied to real people.

Email sign in

No reviews posted yet.

OpenAPI

About

Details

Explore

Setting up with Highlight

Setting up with Cursor

JSON

JSON

JSON

Setting up with Claude Desktop

JSON

JSON

JSON

Setting up with Windsurf

JSON

JSON

JSON

Setting up with Cline

JSON

JSON

JSON

Setting up with Goose

JSON

JSON

JSON

From the repository

`all`

`dynamic`

`explicit`

Claude Desktop / Cursor

Linux

Macos

Windows

📖 Documentation

Videos about OpenAPI

MCP Openapi: How to Give Superpowers to Your AI Chatbot

Why OpenAPI Specs Fail for Complex AI Agents (MCP Demo)

Understanding OpenAPI & MCP

About

Details

Explore

Setting up with Highlight

From the repository

all

dynamic

explicit

Claude Desktop / Cursor

Linux

Macos

Windows

📖 Documentation

Videos about OpenAPI

MCP Openapi: How to Give Superpowers to Your AI Chatbot

Why OpenAPI Specs Fail for Complex AI Agents (MCP Demo)

Understanding OpenAPI & MCP

More like this

Sentry

Github

Git

GitLab

`all`

`dynamic`

`explicit`