Package Exports

universal-openapi-mcp
universal-openapi-mcp/dist/index.js

This package does not declare an exports field, so the exports above have been automatically detected and optimized by JSPM instead. If any package subpath is missing, it is recommended to post an issue to the original package (universal-openapi-mcp) to support the "exports" field. If that is not possible, create a JSPM override to customize the exports field for this package.

Readme

Universal OpenAPI MCP Server

A powerful Model Context Protocol (MCP) server that works with any OpenAPI-compliant API. This server allows you to easily connect to and interact with any API by providing its OpenAPI specification, with support for multiple APIs and various authentication methods.

Features
Installation
Quick Start
Usage with Claude Desktop
Configuration
- Using .env (Environment Variables)
- Using YAML Configuration
Available Tools
Real-World Examples
Troubleshooting
Advanced Features
Development
Architecture Documentation
Contributing
License

Features

Universal API Support: Works with any OpenAPI 3.x or Swagger 2.0 compliant API
Multiple API Management: Configure and switch between multiple APIs
Automatic Validation: Validates OpenAPI specs using @readme/openapi-parser
Flexible Authentication: Support for API Key, Bearer Token, Basic Auth, OAuth2, and custom auth
Dual Configuration: Environment variables OR YAML configuration files
Structured API Discovery: Returns organized JSON data for endpoints grouped by tags
Enhanced Error Reporting: Detailed error messages with request information for debugging
Environment Variable Substitution: Use ${VAR_NAME} in YAML files
TypeScript Support: Fully typed with TypeScript for better development experience
FastMCP Integration: Built with FastMCP for optimal Model Context Protocol support

Installation

Clone the repository:

git clone https://github.com/jonsoku-dev/universal-openapi-mcp.git
cd universal-openapi-mcp

Install dependencies:

npm install

Build the project:

npm run build

Quick Start

Copy the example environment file:

cp .env.example .env

Edit .env with your API details:

# Minimal configuration
API_NAME=petstore
API_BASE_URL=https://petstore.swagger.io/v2
OPENAPI_SPEC_URL=https://petstore.swagger.io/v2/swagger.json

Run the server:

npm run dev

Test with FastMCP:

npx fastmcp dev src/index.ts

Usage with Claude Desktop

To use this server with Claude Desktop, you need to register it in your claude_desktop_config.json file.

Locate your claude_desktop_config.json file. The location varies by operating system:
- macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
- Windows: %APPDATA%\\Claude\\claude_desktop_config.json
- Linux: ~/.config/Claude/claude_desktop_config.json

Open the file and add or update the mcpServers section as follows:

{
  "mcpServers": {
    "universal-openapi-mcp": {
      "command": "npx",
      "args": [
        "universal-openapi-mcp"
      ],
      "env": {
        "OPENAPI_SPEC_URL": "YOUR_OPENAPI_SPEC_URL",
        "API_BASE_URL": "YOUR_API_BASE_URL",
        "API_NAME": "YOUR_API_NAME",
        "API_TIMEOUT": "30000" // Optional
        // Add any other required environment variables for your API
        // (e.g., AUTH_TYPE, API_KEY, etc., as detailed in the [Configuration](#configuration) section).
      }
    }
    // You can add other MCP servers here
  }
}

Important: Replace YOUR_OPENAPI_SPEC_URL, YOUR_API_BASE_URL, and YOUR_API_NAME with the actual values for the API you want to connect to. You can also configure authentication by setting the appropriate environment variables (e.g., AUTH_TYPE, API_KEY, etc., as detailed in the Configuration section) within the env block for the server.
Save the claude_desktop_config.json file. Claude Desktop should automatically pick up the new server configuration.

Configuration

Using .env (Environment Variables)

The simplest way to configure is using a .env file. The server supports comprehensive environment variable configuration for all aspects of API connectivity.

Basic Configuration (Required)

# API Name - Unique identifier for your API
API_NAME=my-api

# API Base URL - The base URL of your API
API_BASE_URL=https://api.example.com

# OpenAPI Specification URL - Where to fetch the spec
# Can be a URL or local file path
OPENAPI_SPEC_URL=https://api.example.com/openapi.json
# or for local files:
# OPENAPI_SPEC_URL=./specs/my-api.yaml

# Request timeout in milliseconds (optional, default: 30000)
API_TIMEOUT=30000

Authentication Methods

The server supports multiple authentication methods. Choose ONE that matches your API:

1. API Key Authentication:

AUTH_TYPE=apiKey
API_KEY=your-api-key-here
API_KEY_LOCATION=header        # or 'query'
API_KEY_NAME=X-API-Key         # The name of the header/query parameter

# Common API key header names:
# - X-API-Key: Generic APIs
# - Authorization: Some services use "Authorization: API-Key YOUR_KEY"
# - X-RapidAPI-Key: RapidAPI services
# - api-key: Azure services
# - X-Auth-Token: Some REST APIs
# - access_token: When passed as query parameter

2. Bearer Token Authentication:

AUTH_TYPE=bearer
# You can use either AUTH_TOKEN or BEARER_TOKEN
BEARER_TOKEN=your-bearer-token-here
# The token will be sent as "Authorization: Bearer TOKEN"

3. Basic Authentication:

AUTH_TYPE=basic
AUTH_USERNAME=your-username
AUTH_PASSWORD=your-password

4. OAuth2 Authentication:

AUTH_TYPE=oauth2
OAUTH2_CLIENT_ID=your-client-id
OAUTH2_CLIENT_SECRET=your-client-secret
OAUTH2_TOKEN_URL=https://api.example.com/oauth/token
OAUTH2_SCOPE=read write        # Space-separated scopes
OAUTH2_GRANT_TYPE=client_credentials  # Usually 'client_credentials' for server-to-server

Custom Headers

Add any custom headers by prefixing with HEADER_. The prefix will be removed and underscores converted to hyphens:

# Examples of header transformation:
# HEADER_USER_AGENT → User-Agent
# HEADER_X_CUSTOM_ID → X-Custom-Id
# HEADER_CONTENT_TYPE → Content-Type

HEADER_USER_AGENT=MyApp/1.0
HEADER_ACCEPT=application/json
HEADER_X_REQUEST_ID=req_123456
HEADER_X_CLIENT_VERSION=2.0
HEADER_X_TENANT_ID=tenant_abc

Using YAML Configuration

For more complex setups or multiple APIs, use YAML configuration. This is especially useful when:

You need to configure multiple APIs
You want to version control your configuration
You have complex authentication setups
You need to use environment variable substitution

Create config.yaml:

apis:
  # GitHub API Example
  github:
    name: github
    baseUrl: https://api.github.com
    openApiSpecUrl: https://raw.githubusercontent.com/github/rest-api-description/main/descriptions/api.github.com/api.github.com.json
    authentication:
      type: bearer
      config:
        token: ${GITHUB_TOKEN}  # Uses environment variable
    defaultHeaders:
      User-Agent: Universal-OpenAPI-MCP/1.0
      Accept: application/vnd.github.v3+json
    timeout: 30000

  # PetStore Example (for testing)
  petstore:
    name: petstore
    baseUrl: https://petstore.swagger.io/v2
    openApiSpecUrl: https://petstore.swagger.io/v2/swagger.json
    timeout: 15000

  # Custom API with API Key
  myapi:
    name: myapi
    baseUrl: ${MY_API_URL}      # Can use env vars anywhere
    openApiSpecUrl: ${MY_API_URL}/openapi.json
    authentication:
      type: apiKey
      config:
        apiKey: ${MY_API_KEY}
        location: header
        keyName: X-API-Key
    defaultHeaders:
      Content-Type: application/json
    timeout: 60000

  # OAuth2 API Example
  oauth_api:
    name: oauth_api
    baseUrl: https://oauth-api.example.com
    openApiSpecUrl: https://oauth-api.example.com/openapi.json
    authentication:
      type: oauth2
      config:
        clientId: ${OAUTH2_CLIENT_ID}
        clientSecret: ${OAUTH2_CLIENT_SECRET}
        tokenUrl: https://oauth-api.example.com/oauth/token
        scope: read write
        grantType: client_credentials
    timeout: 30000

# Set default API (optional)
defaultApi: github

Using YAML Configuration:

# Option 1: Using CONFIG_FILE environment variable
CONFIG_FILE=./config.yaml npm run dev

# Option 2: Using MCP_CONFIG_FILE environment variable
MCP_CONFIG_FILE=./my-config.yaml npm run dev

# Option 3: Set in .env file
echo "CONFIG_FILE=./config.yaml" >> .env
npm run dev

Configuration Priority

If CONFIG_FILE or MCP_CONFIG_FILE is set, it tries to load YAML first
If YAML loading fails, it falls back to environment variables
If no API is specified with API_NAME, it uses the defaultApi from YAML
YAML configuration takes precedence over environment variables when both exist

Available Tools

The server provides four main tools for interacting with APIs:

1. `api_request`

Make HTTP requests to the configured API with detailed error reporting.

Parameters:

path: API endpoint path (e.g., '/users' or '/pet/123')
method: HTTP method (default: 'get')
data: Request body for POST/PUT/PATCH requests
params: Query parameters
headers: Additional headers

Example:

{
  "path": "/pet/123",
  "method": "get"
}

Error Response includes:

Full request URL
HTTP method used
Headers sent (with sensitive data redacted)
Query parameters
Request body
Status code and error message

2. `api_paths_list`

Returns a structured JSON object with all API endpoints organized by tags.

Response format:

{
  "summary": {
    "totalEndpoints": 20,
    "tags": ["pet", "store", "user"]
  },
  "endpoints": {
    "pet": [
      {
        "path": "/pet",
        "method": "POST",
        "operationId": "addPet",
        "summary": "Add a new pet to the store",
        "parameters": [],
        "requestBody": {
          "required": true,
          "contentTypes": ["application/json", "application/xml"]
        }
      }
    ]
  }
}

3. `api_paths_info`

Get detailed OpenAPI specification for specific paths.

Parameters:

path_templates: Array of path templates (e.g., ["/pet", "/pet/{petId}"])

4. `api_spec_info`

Get general information about the API's OpenAPI specification.

Parameters:

include: Array of information types to include
- info: API title, version, description
- servers: Available server URLs
- tags: Tag descriptions
- paths_summary: Summary of all paths with operations

Real-World Examples

Example 1: GitHub API Setup

.env file:

API_NAME=github
API_BASE_URL=https://api.github.com
OPENAPI_SPEC_URL=https://raw.githubusercontent.com/github/rest-api-description/main/descriptions/api.github.com/api.github.com.json
AUTH_TYPE=bearer
BEARER_TOKEN=ghp_your_github_personal_access_token_here
HEADER_ACCEPT=application/vnd.github.v3+json
HEADER_X_GITHUB_API_VERSION=2022-11-28

Example 2: Stripe API Setup

.env file:

API_NAME=stripe
API_BASE_URL=https://api.stripe.com
OPENAPI_SPEC_URL=https://raw.githubusercontent.com/stripe/openapi/master/openapi/spec3.json
AUTH_TYPE=bearer
BEARER_TOKEN=sk_test_your_stripe_secret_key_here
HEADER_STRIPE_VERSION=2023-10-16

Example 3: OpenAI API Setup

.env file:

API_NAME=openai
API_BASE_URL=https://api.openai.com
OPENAPI_SPEC_URL=https://raw.githubusercontent.com/openai/openai-openapi/master/openapi.yaml
AUTH_TYPE=bearer
BEARER_TOKEN=sk-your-openai-api-key-here
HEADER_OPENAI_BETA=assistants=v2

Example 4: Custom Internal API

config.yaml:

apis:
  internal:
    name: internal-api
    baseUrl: https://api.internal.company.com
    openApiSpecPath: ./specs/internal-api.yaml  # Local file
    authentication:
      type: apiKey
      config:
        apiKey: ${INTERNAL_API_KEY}
        location: header
        keyName: X-Company-API-Key
    defaultHeaders:
      X-Request-ID: ${REQUEST_ID}
      X-Client-Version: "2.0"
      X-Tenant-ID: tenant_123
    timeout: 45000

defaultApi: internal

Troubleshooting

Common Issues and Solutions

"No OpenAPI spec URL or path provided"
- Ensure OPENAPI_SPEC_URL is set in .env or config.yaml
- Check that the URL is accessible and returns valid OpenAPI/Swagger spec
- Try opening the URL in your browser to verify
404 Errors when making requests
- Verify API_BASE_URL includes the full base path (e.g., /v2 for PetStore)
- Check if the path you're requesting exists using api_paths_list
- Ensure paths don't have double slashes (e.g., avoid //pet)
Authentication errors
- Double-check your API key/token is correct and not expired
- Verify you're using the correct AUTH_TYPE for your API
- Check authentication type matches API requirements
- Some APIs require specific header names (check API documentation)
- For OAuth2, ensure all required fields are set
"Failed to load configuration"
- Check YAML syntax is valid (use a YAML validator)
- Ensure all environment variables referenced with ${} exist
- Verify file path is correct if using CONFIG_FILE
Timeout errors
- Increase API_TIMEOUT value (default is 30000ms)
- Check network connectivity
- Some APIs have slow endpoints that need longer timeouts

Debug Mode

To see detailed logs and debug information:

# The MCP server logs detailed information about requests and errors
npm run dev

Check the error messages - they include:

Exact URL being requested
Headers being sent (with sensitive data redacted)
Query parameters
Request body (for POST/PUT/PATCH)
Full error stack traces

Advanced Features

Using Local OpenAPI Specs

Instead of a URL, you can use a local file:

apis:
  local:
    name: local-api
    baseUrl: http://localhost:3000
    openApiSpecPath: ./specs/my-api.yaml  # Local file path

Dynamic Headers

Use environment variables for dynamic headers:

# In .env
REQUEST_ID=req_${RANDOM_ID}
SESSION_TOKEN=${DYNAMIC_TOKEN}

# These become headers
HEADER_X_REQUEST_ID=${REQUEST_ID}
HEADER_AUTHORIZATION=Session ${SESSION_TOKEN}

Multiple Authentication Methods

Some APIs support multiple auth methods. Configure the one you prefer:

# OAuth2 for write operations
authentication:
  type: oauth2
  config:
    clientId: ${CLIENT_ID}
    clientSecret: ${CLIENT_SECRET}
    tokenUrl: https://api.example.com/oauth/token
    scope: read write

# Or use API Key for read-only
# authentication:
#   type: apiKey
#   config:
#     apiKey: ${READ_ONLY_KEY}
#     location: header
#     keyName: X-API-Key

Environment Variable Substitution in YAML

The YAML loader supports environment variable substitution using the ${VAR_NAME} syntax:

apis:
  myapi:
    baseUrl: ${API_BASE_URL}
    authentication:
      type: bearer
      config:
        token: ${API_TOKEN}
    defaultHeaders:
      X-Environment: ${ENVIRONMENT:-development}  # With default value

Development

Project Structure

src/
├── index.ts          # Main MCP server
├── types.ts          # TypeScript type definitions
├── auth.ts           # Authentication handlers
├── client.ts         # HTTP client with error handling
├── spec-utils.ts     # OpenAPI specification utilities
├── validation-error.ts  # Custom error classes
└── config-loader.ts  # Configuration loading logic

Available Scripts

# Development mode with hot reload
npm run dev

# Build TypeScript to JavaScript
npm run build

# Run built version
npm start

# Test with FastMCP
npm test

# Inspect MCP capabilities
npm run inspect

# Clean build directory
npm run clean

Building from Source

# Install dependencies
npm install

# Run in development mode (with hot reload)
npm run dev

# Build for production
npm run build

# Run tests
npm test

Architecture Documentation

For a detailed explanation of the server's architecture, please see the ARCHITECTURE.md file.

Contributing

Fork the repository
Create a feature branch (git checkout -b feature/amazing-feature)
Make your changes
Add tests if applicable
Commit your changes (git commit -m 'Add some amazing feature')
Push to the branch (git push origin feature/amazing-feature)
Open a Pull Request

License

MIT License - see LICENSE file for details

Changelog

Version 1.0.0

Complete rewrite with @readme/openapi-parser for better validation
Support for both Swagger 2.0 and OpenAPI 3.x specifications
Enhanced error messages with detailed request information
Structured JSON responses for api_paths_list tool
Improved URL handling for different API structures
Better TypeScript types throughout
Comprehensive environment variable support
YAML configuration with environment variable substitution
Multiple authentication methods (API Key, Bearer, Basic, OAuth2)
Custom header support
FastMCP integration for optimal MCP support