Connect Any OpenAPI to Claude Desktop

A generic Model Context Protocol (MCP) server that dynamically converts OpenAPI specifications into MCP tools, enabling Claude Desktop and other AI systems to interact with any REST API.

TypeScript Node.js MCP Protocol MIT License
Get Started View on GitHub
Terminal 
# Connect any OpenAPI to Claude Desktop
npx @lucid-spark/openapi-mcp-server openapi-mcp-server \
  --api-base-url https://api.example.com \
  --openapi-spec https://api.example.com/openapi.json \
  --headers "Authorization:Bearer token123"

# ✨ 47 tools generated from OpenAPI spec
# 🔗 Server ready for Claude Desktop connection

Powerful Features

Everything you need to connect APIs to AI systems

🔄

Dynamic Tool Generation

Automatically converts OpenAPI operations to MCP tools with intelligent naming and parameter mapping

🔐

Flexible Authentication

Support for static headers, dynamic providers, token refresh, and complex authentication patterns

📊

Advanced Filtering

Filter tools by tags, resources, operations, or explicit lists to expose only what you need

🌐

Multiple Transports

Stdio for Claude Desktop integration, HTTP for web applications with streaming support

📝

Smart Tool Naming

Intelligent abbreviation system with ≤64 character limit and readable formats

⚡

Meta-Tools

Built-in API exploration and dynamic endpoint invocation capabilities

🏗️

Interface-Based Architecture

Type-safe, modular design with comprehensive TypeScript interfaces

📥

Multiple Input Methods

Load OpenAPI specs from URL, file, stdin, or inline content

Quick Start

Get up and running in minutes

1. Configure Claude Desktop

Add to your Claude Desktop configuration file:

JSON 
{
  "mcpServers": {
    "openapi": {
      "command": "npx",
      "args": ["-y", "@lucid-spark/openapi-mcp-server", "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"
      }
    }
  }
}

2. Restart Claude Desktop

Your API endpoints will appear as available tools in Claude conversations.

1. Install globally (optional)

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

2. Run with any OpenAPI-compliant API

npx @lucid-spark/openapi-mcp-server openapi-mcp-server \
  --api-base-url https://api.example.com \
  --openapi-spec https://api.example.com/openapi.json \
  --headers "Authorization:Bearer token123" \
  --transport stdio

1. Install as dependency

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

2. Use in your application

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

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

await server.start();

Architecture Overview

Modular, type-safe design for maximum flexibility

OpenAPI Server

Orchestration & MCP Protocol

Configuration

Validation & Defaults

Type System

Interface-based Safety

Spec Loader

Multiple Inputs & $ref Resolution

Tools Manager

Creation, Filtering & Caching

Authentication

Static & Dynamic Providers

Tool System

ID Generation & Name Abbreviation

API Client

HTTP Requests & Auth Integration

Transport Layer

Stdio (Claude) & HTTP (Web)

Usage Examples

Real-world scenarios and patterns

Public API (No Auth)

openapi-mcp-server \
  --api-base-url https://jsonplaceholder.typicode.com \
  --openapi-spec https://jsonplaceholder.typicode.com/openapi.json

GitHub API

openapi-mcp-server \
  --api-base-url https://api.github.com \
  --openapi-spec https://api.github.com/openapi.json \
  --headers "Authorization:Bearer ghp_xxxx"

Filtered API Subset

openapi-mcp-server \
  --api-base-url https://api.example.com \
  --openapi-spec ./api-spec.yaml \
  --tag public --operation GET

HTTP Transport

openapi-mcp-server \
  --api-base-url https://api.example.com \
  --openapi-spec ./api-spec.yaml \
  --transport http --port 3000

Documentation

Comprehensive guides and references

📦

Installation Guide

Prerequisites, global installation, local setup, and development environment

⚙️

Configuration

Complete configuration options, environment variables, and CLI arguments

🔐

Authentication

Static headers, dynamic providers, token refresh, and complex auth patterns

🛠️

Tool Management

Tool generation, filtering, naming conventions, and meta-tools

🌐

Transport Types

Stdio for Claude Desktop, HTTP for web apps, and session management

🏗️

Architecture Guide

Component design, data flow, interface patterns, and extensibility

📚

API Reference

TypeScript interfaces, method signatures, and library usage
💡

Examples & Patterns

Real-world usage examples, integration patterns, and best practices

🐛

Troubleshooting

Common issues, debug mode, error handling, and solutions

Community & Support

Get help and contribute to the project

GitHub Repository

Source code, issues, and contributions
🐛

Report Issues

Bug reports and feature requests
💬

Discussions

Community help and general discussion
📖

MCP Protocol

Official Model Context Protocol documentation