1
Add it to Claude Code
claude mcp add -e "API_BASE_URL=${API_BASE_URL}" -e "OPENAPI_SPEC_PATH=${OPENAPI_SPEC_PATH}" openapi-mcp-server -- npx -y @lucid-spark/openapi-mcp-serverRequired:
API_BASE_URLOPENAPI_SPEC_PATH+ 1 optional2
Make your agent remember this setup
openapi-mcp-server's config, env vars, and the gotchas you hit — recalled in every future Claude Code, Cursor, and Codex session.
npx conare@latestFree · one command · indexes the sessions already on disk. Set up in the browser instead →
What it does
- Dynamic conversion of OpenAPI operations into MCP tools
- Support for multiple authentication methods including static headers and dynamic providers
- Advanced tool filtering by tags, resources, or operations
- Multiple transport support including stdio and HTTP
- Intelligent tool naming with character limit enforcement
Tools 1
dynamic-api-toolsAutomatically generated tools based on the provided OpenAPI specification operations.Environment Variables
API_BASE_URLrequiredThe base URL of the target REST APIOPENAPI_SPEC_PATHrequiredURL or local path to the OpenAPI JSON specificationTRANSPORT_TYPECommunication protocol (stdio or http)Try it
→List all available operations for the connected API.
→Fetch the user profile using the get-user-details tool.
→Create a new resource using the provided API schema.
→Search for items in the API matching the query 'example'.
Original README from luciVuc/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