OpenAPI MCP Server

OpenAPI MCP Server

A generic Model Context Protocol (MCP) server that dynamically exposes OpenAPI-defined REST APIs as MCP tools. This enables Large Language Models like Claude to discover and interact with any OpenAPI-compliant API through the standardized MCP protocol.

✨ Key Features

• 🔄 Dynamic Tool Generation: Automatically converts OpenAPI operations to MCP tools
• 🔐 Flexible Authentication: Static headers, dynamic providers, token refresh
• 📊 Advanced Filtering: Filter tools by tags, resources, operations, or explicit lists
• 🌐 Multiple Transports: Stdio for Claude Desktop, HTTP for web applications
• 📝 Smart Tool Naming: Intelligent abbreviation with ≤64 character limit
• � Meta-Tools: Built-in API exploration and dynamic endpoint invocation
• 🏗 Interface-Based Architecture: Type-safe, modular design with comprehensive interfaces
• 📥 Multiple Input Methods: URL, file, stdin, or inline OpenAPI specifications

🚀 Quick Start

CLI Usage (Recommended)

# Install globally
npm install -g @lucid-spark/openapi-mcp-server

# Use with any OpenAPI-compliant API
openapi-mcp-server \
  --api-base-url https://api.example.com \
  --openapi-spec https://api.example.com/openapi.json \
  --transport stdio

Docker Usage (Production Ready)

# Run with HTTP transport
docker run --rm -p 3000:3000 \
  -e API_BASE_URL=https://petstore.swagger.io/v2 \
  -e OPENAPI_SPEC_PATH=https://raw.githubusercontent.com/readmeio/oas-examples/main/3.0/json/petstore.json \
  -e TRANSPORT_TYPE=http \
  reallv/openapi-mcp-server:latest

# Run with stdio transport (for Claude Desktop)
docker run --rm -i \
  -e API_BASE_URL=https://api.example.com \
  -e OPENAPI_SPEC_PATH=https://api.example.com/openapi.json \
  reallv/openapi-mcp-server:latest

# Use docker-compose for multiple APIs
docker-compose up -d

Library Usage

npm install @lucid-spark/openapi-mcp-server

import { OpenAPIServer } from "@lucid-spark/openapi-mcp-server";

const server = new OpenAPIServer({
  apiBaseUrl: "https://api.example.com",
  openApiSpec: "https://api.example.com/openapi.json",
  transportType: "stdio",
});

await server.start();

📖 Documentation

• Complete Documentation - Comprehensive guide with examples and patterns
• Library Usage - For developers creating custom MCP servers using this package
• Developer Guide - For contributors and developers working on the codebase
• Examples Directory - Practical usage examples and patterns

For MCP protocol details, see modelcontextprotocol.io.

📋 Table of Contents

• Architecture
• Installation
• Configuration
• Docker Usage
• Usage Examples
• Claude Desktop Integration
• Authentication
• Tool Management
• Transport Types
• API Documentation
• Development
• Examples
• Troubleshooting

🏗 Architecture

The OpenAPI MCP Server uses a modular, interface-based architecture for maximum flexibility and type safety:

┌─────────────────────┐    ┌─────────────────────┐    ┌─────────────────────┐
│   OpenAPI Server    │    │    Configuration    │    │    Type System      │
│                     │    │                     │    │                     │
│ • Orchestration     │◄──►│ • Validation        │◄──►│ • Interface-based   │
│ • MCP Protocol      │    │ • Defaults          │    │ • Type Safety       │
│ • Lifecycle Mgmt    │    │ • Environment Vars  │    │ • Extensibility     │
└─────────────────────┘    └─────────────────────┘    └─────────────────────┘
          │                          │                          │
          ▼                          ▼                          ▼
┌─────────────────────┐    ┌─────────────────────┐    ┌─────────────────────┐
│  OpenAPI Spec       │    │   Tools Manager     │    │   Authentication    │
│  Loader             │    │                     │    │   System            │
│                     │    │ • Tool Creation     │    │                     │
│ • Multiple Inputs   │    │ • Filtering         │    │ • Static Headers    │
│ • $ref Resolution   │    │ • Lookup & Cache    │    │ • Dynamic Providers │
│ • Schema Processing │    │ • Meta-tool