OpenAPI MCP Server

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

Quick Start

You do not need to clone this repository to use this MCP server. You can simply configure it in Claude Desktop:

Locate or create your Claude Desktop configuration file:
- On macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
Add the following configuration to enable the OpenAPI MCP server:

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

Replace the environment variables with your actual API configuration:
- API_BASE_URL: The base URL of your API
- OPENAPI_SPEC_PATH: URL or path to your OpenAPI specification
- API_HEADERS: Comma-separated key:value pairs for API authentication headers

Development Tools

This project includes several development tools to make your workflow easier:

Building

npm run build - Builds the TypeScript source
npm run clean - Removes build artifacts
npm run typecheck - Runs TypeScript type checking

Development Mode

npm run dev - Watches source files and rebuilds on changes
npm run inspect-watch - Runs the inspector with auto-reload on changes

Code Quality

npm run lint - Runs ESLint
npm run typecheck - Verifies TypeScript types

Configuration

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

Environment Variables

API_BASE_URL - Base URL for the API endpoints
OPENAPI_SPEC_PATH - Path or URL to OpenAPI specification
API_HEADERS - Comma-separated key:value pairs for API headers
SERVER_NAME - Name for the MCP server (default: "mcp-openapi-server")
SERVER_VERSION - Version of the server (default: "1.0.0")

Command Line Arguments

npm run inspect -- \
  --api-base-url https://api.example.com \
  --openapi-spec https://api.example.com/openapi.json \
  --headers "Authorization:Bearer token123,X-API-Key:your-api-key" \
  --name "my-mcp-server" \
  --version "1.0.0"

Development Workflow

Start the development environment:

npm run inspect-watch

Make changes to the TypeScript files in src/
The server will automatically rebuild and restart
Use the MCP Inspector UI to test your changes

Debugging

The server outputs debug logs to stderr. To see these logs:

In development mode:
- Logs appear in the terminal running inspect-watch
When running directly:
npm run inspect 2>debug.log

Contributing

Fork the repository
Create a feature branch
Make your changes
Run tests and linting:
npm run typecheck npm run lint
Submit a pull request

License

MIT