🚀 Universal Swagger → MCP Server Converter

Stop wrestling with massive API docs in your AI assistant's context window. Start having intelligent conversations about any API.

---

⭐ Love this project? Give it a star! ⭐

🚀 Help us reach more developers who struggle with API integrations!
Your star makes this project more discoverable and motivates continued development.

⭐ Star this repo | 🍴 Fork it | 📢 Share it

---

💡 The Problem Every Developer Faces

You're building an integration with a complex API. The Swagger documentation is 2MB+ of JSON. Your AI assistant can only see tiny fragments at a time. You end up:

• ❌ Copy-pasting documentation chunks into chat windows
• ❌ Missing crucial schema relationships between endpoints
• ❌ Getting outdated or incomplete code examples
• ❌ Losing context when working across multiple API endpoints
• ❌ Wasting hours on what should be simple integrations

✨ The Solution: Intelligent API Knowledge for AI

Transform any Swagger/OpenAPI specification into an intelligent MCP server that gives your AI assistant superpowers:

🎯 What Your AI Can Now Do:

# Instead of this painful workflow:
"Here's a 500KB Swagger file, please help me integrate..."
# Error: Context window exceeded

# You get this magical experience:
AI: "I need to create a user and get their profile data"
→ Instantly finds relevant endpoints: POST /users, GET /users/{id}
→ Generates complete TypeScript client with proper types
→ Includes error handling and authentication patterns
→ Shows example requests/responses for testing

🚀 From 0 to AI-Powered API Integration in 30 Seconds:

# 1. Convert any Swagger file to intelligent MCP server
swagger-mcp-server convert your-api.json

# 2. Connect to Cursor, Claude, or VS Code
# Your AI assistant now knows EVERYTHING about your API

# 3. Start building with superhuman API knowledge
"Create a React hook for user authentication with retry logic"
"Generate Python client for the payment endpoints"
"Show me all endpoints that return user data"

🌟 Real-World Impact:

• ⚡ 10x Faster Integration: From hours to minutes for complex APIs
• 🎯 Perfect Code Generation: AI understands full API context and relationships
• 🔍 Instant API Discovery: Natural language search across any documentation size
• 🛡️ Enterprise Ready: Works offline, handles massive APIs (10MB+), production deployment
• 🔌 Universal Compatibility: Cursor, Claude, VS Code, or any MCP-compatible tool

---

Ready to supercharge your API development workflow? Jump to 🚀 Quick Start and experience the future of AI-assisted API integration.

📋 Table of Contents

• ✨ What is swagger-mcp-server?
• 🚀 Quick Start - Get running in 5 minutes
• 🏗️ Architecture - System overview
• 🔍 MCP Server Methods - API reference
• 🔧 CLI Commands - Command reference
• 🤖 AI Tool Integrations - VS Code, Cursor setup
• 📝 Configuration - Basic setup
• 💡 Examples - Sample APIs and use cases
• 🔧 Troubleshooting - Common issues
• 📚 Complete Documentation - All guides
• 🆘 Getting Help - Support resources

✨ What is swagger-mcp-server?

swagger-mcp-server bridges the gap between API documentation and AI coding assistants. Instead of AI agents struggling with large API docs in their context window, they can now query specific information on-demand through the Model Context Protocol (MCP).

Key Benefits

• 🔍 Intelligent Search: Find relevant endpoints using natural language queries
• 📊 Schema Awareness: Get complete type information and relationships
• 💻 Code Generation: Generate working examples in multiple languages
• ⚡ Fast Responses: Sub-200ms search, optimized for AI agent workflows
• 🔌 Easy Integration: Works with VS Code, Cursor, and custom AI tools
• 🛡️ Production Ready: SSL, authentication, monitoring, and deployment guides

Use Cases

• API Integration: Help AI assistants understand and use your APIs correctly
• Documentation Search: Quickly find specific endpoints and schemas
• Code Generation: Generate accurate API client code and examples
• API Exploration: Discover API capabilities through intelligent search
• Development Workflow: Integrate API knowledge into your coding environment

🚀 Quick Start

Step 1: Get Your Swagger JSON File

Before converting, you need to obtain the Swagger/OpenAPI JSON specification from any API documentation site:

🔍 Finding the Swagger JSON (Most Common Method)

1. Visit any API documentation website (e.g., docs.example.com/api)
2. Open Browser DevTools (F12 or Cmd/Ctrl + Shift + I)
3. Go to Network tab and refresh the page
4. Look for swagger.json or similar files in the network requests
5. Click on the JSON file and copy the response
6. Save it to your project in the swagger-openapi-data/ directory:

# Save the JSON content to the existing swagger-openapi-data directory
# Either copy-paste or download directly:
curl -o swagger-openapi-data/your-api.json "https://api.example.com/swagger.json"

# Or save manually by copying the JSON content and pasting it into:
# swagger-openapi-data/your-api.json

📋 Alternative Methods to Get Swagger JSON

Method 2: Direct URL Access

# Many APIs expose Swagger at common endpoints:
curl -o swagger-openapi-data/your-api.json "https://api.example.com/swagger.json"
curl -o swagger-openapi-data/your-api.json "https://api.example.com/v1/swagger.json"
curl -o swagger-openapi-data/your-api.json "https://api.example.com/docs/swagger.json"

Method 3: API Documentation Download Most API documentation sites have a "Download OpenAPI" or "Export JSON" button.

Method 4: Use Our Sample API (Already Included)

# We already include a sample Ozon Performance API for testing:
ls swagger-openapi-data/swagger.json  # 262KB Ozon API ready to use

Step 2: Installation

# Option 1: Install from source (recommended)
git clone https://github.com/salacoste/openapi-mcp-swagger.git
cd openapi-mcp-swagger

# Option 2: Install dependencies
pip install -r requirements.txt

# Option 3: Use standalone script (no installation required)
chmod +x scripts/standalone-mcp.py

Step 3: Convert & Start

# Convert your Swagger file to MCP server
swagger-mcp-server convert swagger-openapi-data/your-api.json --name your-api

# Or use the included sample API
swagger-mcp-server convert swagger-openapi-data/swagger.json --name ozon-api

# Start the MCP server
cd mcp-server-your-api  # or mcp-server-ozon-api
swagger-mcp-server serve

# 4. Test with AI agents or curl
curl -X POST http://localhost:8080 \
  -H "Content-Type: application/json" \
  -d '{"jsonrpc":"2.0","id":1,"method":"searchEndpoints","params":{"keywords":"user"}}'

Step 4: What Happens Next

🎉 Congratulations! Your API is now AI-ready. Here's what you get:

🧠 Intelligent API Knowledge

• Complete endpoint mapping with search capability
• Schema relationships preserved and queryable
• Code examples generated on-demand in multiple languages
• Context-aware responses for any API size

🤖 AI Assistant Integration

Connect to your favorite AI coding assistant:

For Cursor IDE:

# Add to .cursor-mcp/config.json
{
  "mcpServers": {
    "your-api": {
      "command": "swagger-mcp-server",
      "args": ["serve", "--port", "8080"]
    }
  }
}

For Claude/VS Code:

# Server will automatically integrate via MCP protocol
# Just point your AI assistant to: http://localhost:8080

✨ Start Building with AI Superpowers

Now you can ask your AI assistant:

"Create a TypeScript client for the user authentication endpoints"
"Show me all endpoints that handle payment processing"  
"Generate a React hook for real-time order status updates"
"What are the required fields for creating a new product?"

📖 Complete Quick Start: Follow our step-by-step Quick Start Tutorial to get your first MCP server running in 5 minutes with sample data.

🏗️ Architecture

The system consists of four main components:

┌─────────────────┐    ┌──────────────────┐    ┌─────────────────┐
│   AI Agent      │◄──►│   MCP Server     │◄──►│  Search Engine  │
│                 │    │                  │    │                 │
│ • Claude        │    │ • JSON-RPC API   │    │ • Endpoint Index│
│ • GPT-4         │    │ • Authentication │    │ • Schema Index  │
│ • Cursor        │    │ • Rate Limiting  │    │ • Full-Text     │
│ • VS Code       │    │ • Monitoring     │    │ • Relationships │
└─────────────────┘    └──────────────────┘    └─────────────────┘
                                │
                                ▼
                       ┌──────────────────┐
                       │  Swagger Parser  │
                       │                  │
                       │ • Validation     │
                       │ • Schema Extract │
                       │ • Relationship   │
                       │ • Indexing       │
                       └──────────────────┘

Core Components

• 🔍 Parser: Stream-based JSON parsing for large OpenAPI files (up to 10MB)
• 💾 Storage: SQLite database with optimized search indexes and relationships
• 🌐 Server: MCP protocol implementation with JSON-RPC over HTTP
• 🔗 Search: Intelligent endpoint and schema search with relevance ranking
• 💻 Examples: Multi-language code generation (cURL, JavaScript, Python, Go)

📖 Detailed Architecture: See docs/architecture/ for complete technical documentation and design decisions.

🔧 Development Setup

Prerequisites

• Python 3.11 or higher (tested with Python 3.13.3)
• Poetry (recommended for dependency management) or pip
• pipx (for Poetry installation)
• Git

System Dependencies

Install system dependencies first:

# macOS (using Homebrew)
brew install python@3.13 pipx

# Ubuntu/Debian
sudo apt update
sudo apt install python3.11-dev python3.11-venv python3-pip pipx