Openai To Mcp

OpenAPI to MCP Server

[](https://npmjs.com/package/openai-to-mcp)

A Model Context Protocol (MCP) server that converts any OpenAPI/Swagger specification into an MCP server, allowing Large Language Models (LLMs) to interact with REST APIs through a standardized interface.

Why Use OpenAPI to MCP?

The OpenAPI to MCP server bridges the gap between REST APIs and LLM agents by:

• Automatically converting API specifications into MCP-compatible tools
• Providing type-safe interactions with any REST API
• Eliminating the need for manual tool creation and maintenance

Client Configuration

Add the OpenAPI to MCP server to your MCP client's configuration file:

{
  "mcpServers": {
    "my-api": {
      "command": "npx",
      "args": [
        "-y",
        "openapi-to-mcp"
      ],
      "env": {
        "OPENAPI_SPEC_URL": "path/to/your/swagger.yml",
        "OPENAPI_SPEC_BASE_URL": "http://api.example.com"
      }
    }
  }
}

Configuration file locations for supported clients:

• Claude Desktop
• macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
• Windows: %APPDATA%\Claude\claude_desktop_config.json

• Cursor: ~/.cursor/mcp.json

• Windsurf: ~/.codeium/windsurf/mcp_config.json

• VS Code:
• Workspace configuration: .vscode/mcp.json
• Command line:

``bash code --add-mcp "{\"name\":\"openapi-mcp\",\"command\":\"npx\",\"args\":[\"-y\",\"openapi-to-mcp\"],\"env\":{\"OPENAPI_SPEC_URL\":\"path/to/your/swagger.yml\",\"OPENAPI_SPEC_BASE_URL\":\"http://api.example.com\"}}" ``

Example .vscode/mcp.json: ``json { "servers": { "openapi-mcp": { "type": "stdio", "command": "npx", "args": ["-y", "openapi-to-mcp"], "env": { "OPENAPI_SPEC_URL": "path/to/your/swagger.yml", "OPENAPI_SPEC_BASE_URL": "http://api.example.com" } } } } ``

Example Usage

Here's an example of how the server converts OpenAPI operations into MCP tools:

OpenAPI Specification

paths:
  /pets:
    get:
      operationId: getPets
      summary: List all pets
      parameters:
        - name: limit
          in: query
          type: integer

Generated MCP Tool

{
  name: "getPets",
  description: "List all pets",
  parameters: {
    limit: z.number().int().optional()
  }
}

Features in Detail

1. API Specification Support

• OpenAPI 2.0 (Swagger)
• OpenAPI 3.0
• Local file paths
• Remote HTTP URLs
• YAML and JSON formats

2. Authentication

The server supports various authentication methods:

API Key Authentication

{
  "env": {
    "OPENAPI_SPEC_HEADERS": "{\"X-API-Key\": \"your-api-key\"}"
  }
}

Bearer Token

{
  "env": {
    "OPENAPI_SPEC_HEADERS": "{\"Authorization\": \"Bearer your-token\"}"
  }
}

Certificate-Based Authentication

{
  "env": {
    "OPENAPI_CERT_PATH": "/path/to/client.crt",
    "OPENAPI_KEY_PATH": "/path/to/client.key",
    "OPENAPI_CERT_PASSPHRASE": "optional-passphrase"
  }
}

OAuth2 Authentication

{
  "env": {
    "OPENAPI_OAUTH_CLIENT_ID": "your-client-id",
    "OPENAPI_OAUTH_CLIENT_SECRET": "your-client-secret",
    "OPENAPI_OAUTH_TOKEN_URL": "https://auth.example.com/oauth/token",
    "OPENAPI_OAUTH_SCOPES": "read:data,write:data"
  }
}

3. Request/Response Handling

• Automatic parameter validation
• JSON Schema to Zod conversion
• Content type negotiation
• File uploads
• Binary responses
• Error mapping

4. Type Safety

• Full TypeScript support
• Automatic type generation
• Runtime type validation
• Type-safe API calls

Command Line Flags

• --spec : Path to OpenAPI specification file
• --base-url : Base URL for API requests
• --headers : Additional headers as JSON string
• --verbose: Enable detailed logging
• --log-level : Set log level (error, warn, info, debug)
• --cert-path : Path to client certificate file
• --key-path : Path to client key file
• --cert-passphrase : Passphrase for certificate
• --oauth-client-id : OAuth client ID
• --oauth-client-secret : OAuth client secret
• --oauth-token-url : OAuth token endpoint URL
• --oauth-scopes : Comma-separated list of OAuth scopes
• --version: Display version information
• --help: Show help information

Docker Support

Building the Docker Image

To build the Docker image:

# Clone the repository
git clone https://github.com/your-username/openapi-to-mcp
cd openapi-to-mcp

# Build the Docker image
docker build -t openapi-to-mcp .

Running the Container

You can run the server using Docker:

docker run \
  -e OPENAPI_SPEC_URL="https://petstore.swagger.io/v2/swagger.json" \
  -e OPENAPI_SPEC_BASE_URL="https://petstore.swagger.io/v2" \
  openapi-to-mcp

Environment Variables

The server uses the following environment variables:

| Variable | Description | Requirement | Notes | |----------|-------------|------------|-------| | OPENAPISPECURL | Path or URL to OpenAPI spec | Required | Local file path or HTTP(S) URL | | OPENAPISPECBASEURL | Base URL for API requests | Required | API server base URL | | OPENAPISPECHEADERS | Additional headers as JSON | Optional | Used for API key and token auth | | OPENAPICERTPATH | Path to client certificate | Optional | Required for certificate auth | | OPENAPIKEYPATH | Path to client key | Optional | Required for certificate auth | | OPENAPICERTPASSPHRASE | Passphrase for client key | Optional | Only needed if key is encrypted | | OPENAPIOAUTHCLIENTID | OAuth client ID | Optional | Required for OAuth2 auth | | OPENAPIOAUTHCLIENTSECRET | OAuth client secret | Optional | Required for OAuth2 auth | | OPENAPIOAUTHTOKENURL | OAuth token URL | Optional* | Required for OAuth2 auth | | OPENAPIOAUTHSCOPES | OAuth scopes (comma-separated) | Optional | Used for OAuth2 scope requests | | NODEEXTRACACERTS | Custom CA certificates path | Optional | For self-signed certificates | | NODETLSREJECTUNAUTHORIZED | Disable TLS validation (0 or 1) | Optional | Use with caution for testing | | LOG_LEVEL | Log level (error, warn, info, debug) | Optional | Defaults to "info" |

> *These variables are conditionally required depending on the authentication method you're using.

Troubleshooting

Enable Debug Logs

npx openapi-to-mcp --debug

Common Issues

1. Version Conflicts

• Ensure Node.js version ≥ 18
• Check package.json for compatibility

Logs Location

• MacOS / Linux:

``bash tail -f ~/.openapi-mcp/logs/server.log ``

• Windows:

``powershell Get-Content "$env:USERPROFILE\.openapi-mcp\logs\server.log" -Wait ``

1. Spec Parser: Loads and validates the OpenAPI specification
2. Operation Generator: Converts API operations to MCP tools
3. MCP Tools: Exposes operations as standardized tools
4. API Calls: Makes actual HTTP requests to the API

Contributing

1. Fork the repository
2. Create a feature branch
3. Commit your changes
4. Push to the branch
5. Create a Pull Request

Development Setup

git clone https://github.com/your-username/openapi-to-mcp
cd openapi-to-mcp
npm install
npm run build
npm run start

Testing

Run the test suite:

npm test

Start the test server:

npm run start:server

License

MIT License - see LICENSE file for details

Support

• Open an issue

Source & license

This open-source MCP server is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: tuvia-r
• Source: tuvia-r/openai-to-mcp
• License: MIT

Install and usage instructions live in the source repository linked above.