Installation Guide

Complete installation guide for OpenAPI MCP Server including prerequisites, global installation, local setup, and development environment.

Prerequisites

Before installing OpenAPI MCP Server, ensure you have the following prerequisites:

Node.js

Version: 18.0.0 or higher

Recommended: Use the latest LTS version

# Check your Node.js version
node --version

# Should output v18.0.0 or higher

Installation: Download from nodejs.org or use a version manager like nvm.

npm

Version: 8.0.0 or higher

Note: npm is included with Node.js

# Check your npm version
npm --version

# Update npm if needed
npm install -g npm@latest

TypeScript (Development Only)

Version: 5.3.0 or higher

Note: Only required for development and building from source 

# Install TypeScript globally (optional)
npm install -g typescript

# Check version
tsc --version

Installation Methods

Choose the installation method that best fits your use case:

🚀 Quick Start (No Installation)

The fastest way to get started is using npx to run the server directly without installation: 

# Run directly with npx (recommended for testing)
npx @lucid-spark/openapi-mcp-server openapi-mcp-server \
  --api-base-url https://api.example.com \
  --openapi-spec https://api.example.com/openapi.json \
  --transport stdio

Advantages:

  • No global installation required
  • Always uses the latest version
  • Perfect for testing and one-off usage
  • Ideal for Claude Desktop configuration

🌐 Global Installation (CLI Usage)

Install the OpenAPI MCP Server globally to use the CLI from anywhere: 

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

# Verify installation
openapi-mcp-server --version

# Use the CLI
openapi-mcp-server \
  --api-base-url https://api.example.com \
  --openapi-spec https://api.example.com/openapi.json

Advantages:

  • Available system-wide as openapi-mcp-server command
  • Faster startup (no download time)
  • Consistent version across projects
  • Good for frequent CLI usage

📦 Local Installation (Library Usage)

Install as a dependency in your Node.js project to use as a library: 

# Navigate to your project directory
cd your-project

# Install as a dependency
npm install @lucid-spark/openapi-mcp-server

# Install as a dev dependency (if only needed for development)
npm install --save-dev @lucid-spark/openapi-mcp-server
// Use in your TypeScript/JavaScript code
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();

Advantages:

  • Use as a library in your applications
  • Custom authentication with AuthProvider
  • Version pinning and dependency management
  • TypeScript support and type definitions

🛠️ Development Installation

Clone and set up the repository for development and contribution: 

# Clone the repository
git clone https://github.com/lucivuc/openapi-mcp-server.git
cd openapi-mcp-server

# Install dependencies
npm install

# Build the project
npm run build

# Run tests
npm test

# Start development server
npm run dev:petstore:v3:json

Advantages:

  • Full source code access
  • Contribute to the project
  • Custom modifications and features
  • Run examples and tests

Installation Verification

Verify your installation works correctly:

1. Test CLI Access

# For global installation
openapi-mcp-server --version

# For npx usage
npx @lucid-spark/openapi-mcp-server openapi-mcp-server --version

# Should output: 1.0.0 (or current version)

2. Test with Public API

# Test with JSONPlaceholder API (no auth required)
npx @lucid-spark/openapi-mcp-server openapi-mcp-server \
  --api-base-url https://jsonplaceholder.typicode.com \
  --openapi-spec https://jsonplaceholder.typicode.com/openapi.json \
  --transport stdio \
  --debug

Look for output indicating successful tool generation:

✅ Loaded OpenAPI specification
✅ Generated X tools from specification
✅ Server ready for MCP connections

3. Test Library Import

Create a test file to verify library usage:

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

console.log("OpenAPIServer imported successfully");
console.log(typeof OpenAPIServer); // Should output: function
# Run the test
npx ts-node test-import.ts

Installation Troubleshooting

Node.js Version Issues

Problem: "Node.js version not supported" error

Solution:

# Check your Node.js version
node --version

# If version is less than 18.0.0, update Node.js
# Using nvm (recommended):
nvm install --lts
nvm use --lts

# Or download from nodejs.org

Permission Errors (Global Installation)

Problem: EACCES permission errors during global installation

Solution:

# Option 1: Use npx instead (recommended)
npx @lucid-spark/openapi-mcp-server openapi-mcp-server --version

# Option 2: Configure npm to use a different directory
mkdir ~/.npm-global
npm config set prefix '~/.npm-global'
echo 'export PATH=~/.npm-global/bin:$PATH' >> ~/.bashrc
source ~/.bashrc

# Option 3: Use sudo (not recommended)
sudo npm install -g @lucid-spark/openapi-mcp-server

Network/Proxy Issues

Problem: Cannot download package from npm registry

Solution:

# Check npm configuration
npm config list

# Configure proxy if needed
npm config set proxy http://proxy.company.com:8080
npm config set https-proxy http://proxy.company.com:8080

# Use different registry if needed
npm config set registry https://registry.npmjs.org/

# Clear npm cache
npm cache clean --force

TypeScript Compilation Errors

Problem: Build fails with TypeScript errors

Solution:

# Ensure TypeScript is installed
npm install -g typescript

# Check TypeScript version
tsc --version

# Clean and rebuild
npm run clean
npm run build

# Install exact dependencies
rm -rf node_modules package-lock.json
npm install

Module Import Errors

Problem: "Cannot find module" errors when importing

Solution:

# Ensure package is installed
npm list @lucid-spark/openapi-mcp-server

# Reinstall if necessary
npm uninstall @lucid-spark/openapi-mcp-server
npm install @lucid-spark/openapi-mcp-server

# Check your tsconfig.json for module resolution settings

Next Steps

After successful installation, you can:

📋 Configure Your Server

Learn about all configuration options, environment variables, and CLI arguments.

🚀 Quick Start Guide

Follow our quick start guide to get your first MCP server running.

🔐 Set Up Authentication

Configure authentication for your APIs with static headers or dynamic providers.

💡 Explore Examples

See real-world examples and integration patterns.