salacoste/openapi-mcp-swagger

🚀 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.

💡 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 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 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

# Install Poetry
pipx install poetry

Local Development

1. Clone and setup:

   git clone https://github.com/salacoste/openapi-mcp-swagger.git
   cd openapi-mcp-swagger
   

2. Setup virtual environment and install dependencies:

   Option A: Using Poetry (Recommended):

   # Install all dependencies including dev dependencies
   poetry install --with dev
   
   # Activate virtual environment
   poetry shell
   

   Option B: Using pip with virtual environment:

   # Create virtual environment
   python3 -m venv .venv
   source .venv/bin/activate  # On Windows: .venv\Scripts\activate
   
   # Upgrade pip
   pip install --upgrade pip
   
   # Install essential dependencies for development
   pip install pytest pytest-asyncio aiosqlite sqlalchemy structlog greenlet
   
   # Install optional dev dependencies
   pip install black isort flake8 mypy pytest-cov
   

3. Verify installation:

   # Test import of main modules
   python -c "
   import sys; sys.path.append('src')
   from swagger_mcp_server.storage.migrations import Migration
   print('✅ Installation successful!')
   "
   

4. Run tests:

   # With Poetry
   poetry run pytest src/tests/unit/test_storage/ -v
   
   # With pip/venv (make sure .venv is activated)
   PYTHONPATH=src python -m pytest src/tests/unit/test_storage/ -v
   
   # Run performance tests
   PYTHONPATH=src python -m pytest src/tests/performance/ -v
   
   # Run with coverage
   pytest --cov=src/swagger_mcp_server --cov-report=html
   

5. Run linting:

   # Format code
   black src/
   isort src/
   
   # Check linting
   flake8 src/
   mypy src/swagger_mcp_server/
   

🧪 Testing

The project uses a comprehensive testing strategy:

• Unit Tests: 80%+ coverage requirement, focused on individual components
• Integration Tests: Full MCP server workflow testing
• Performance Tests: Validation of response time requirements (<200ms search, <500ms schema)
• Fixtures: Sample OpenAPI specifications for consistent testing

Running Tests

# All tests with coverage
poetry run pytest --cov=swagger_mcp_server --cov-report=html

# Unit tests only
poetry run pytest -m unit

# Integration tests only
poetry run pytest -m integration

# Performance/benchmark tests
poetry run pytest -m performance --benchmark-only

📁 Project Structure

swagger-mcp-server/
├── src/
│   ├── swagger_mcp_server/        # Main package
│   │   ├── parser/                # OpenAPI parsing
│   │   ├── storage/               # Database layer
│   │   ├── server/                # MCP implementation
│   │   ├── config/                # Configuration
│   │   └── examples/              # Code generation
│   └── tests/                     # Test suite
├── scripts/                       # Utility scripts
├── data/                          # Sample data
├── docs/                          # Documentation
├── .github/                       # CI/CD workflows
└── pyproject.toml                 # Project configuration

🔍 MCP Server Methods

The server implements three core MCP methods:

searchEndpoints(keywords, httpMethods)

Search for API endpoints using keywords and HTTP method filters.

// Example usage
const results = await mcpClient.call('searchEndpoints', {
  keywords: ['user', 'authentication'],
  httpMethods: ['GET', 'POST']
});

getSchema(componentName)

Retrieve complete schema definitions with dependencies.

const schema = await mcpClient.call('getSchema', {
  componentName: 'User'
});

getExample(endpoint, format)

Generate working code examples in multiple formats.

const example = await mcpClient.call('getExample', {
  endpoint: '/api/users',
  format: 'curl'  // 'curl', 'javascript', 'python'
});

📖 Complete API Reference: See for detailed protocol documentation, client libraries, and integration examples.

🔧 CLI Commands

Essential commands for everyday use:

# Convert Swagger to MCP server
swagger-mcp-server convert api.json --name my-api --port 8080

# Start server
swagger-mcp-server serve --config config.yaml

# Check server status
swagger-mcp-server status --all

# Configuration management
swagger-mcp-server config create production --output prod-config.yaml

# Setup and installation
swagger-mcp-server setup --verify

📖 Complete CLI Reference: See for all commands, options, and usage examples.

⚡ Performance Requirements

• Search Response: < 200ms target, < 500ms maximum
• Schema Retrieval: < 500ms target, < 1s maximum
• File Processing: < 2s for files up to 5MB
• Memory Usage: Process 10MB files within 2GB RAM
• Concurrency: Support 100+ concurrent AI agent connections

📖 Performance Tuning: See for optimization strategies and scaling guidelines.

🤖 AI Tool Integrations

swagger-mcp-server works seamlessly with popular AI coding assistants:

VS Code + Continue

{
  "mcpServers": {
    "my-api": {
      "command": "swagger-mcp-server",
      "args": ["serve", "--config", "config.yaml"]
    }
  }
}

Cursor AI

{
  "mcp": {
    "servers": {
      "api-docs": "http://localhost:8080"
    }
  }
}

📖 Integration Guides: See for complete setup instructions for VS Code, Cursor, and custom AI agents.

📝 Configuration

Basic Configuration

# config.yaml
server:
  host: localhost
  port: 8080

database:
  path: ./mcp_server.db

search:
  index_directory: ./search_index

logging:
  level: INFO
  console: true

Environment-Specific Configs

• Development:
• Production:

📖 Configuration Guide: See for configuration basics and for complete reference.

💡 Examples

Sample APIs

We provide realistic sample APIs for testing:

• E-commerce Platform (45 endpoints):
• Banking API (67 endpoints):
• Healthcare API (52 endpoints):

Quick Test

# Use our sample e-commerce API
swagger-mcp-server examples create-sample --type ecommerce --output sample-api.json
swagger-mcp-server convert sample-api.json --name demo
cd mcp-server-demo && swagger-mcp-server serve

📖 Examples Catalog: See for all available sample APIs and use cases.

🤝 Contributing

We welcome contributions! Please see our for details.

Development Workflow

1. Fork the repository
2. Create a feature branch: git checkout -b feat/my-feature
3. Make your changes with tests
4. Run the test suite: pytest
5. Run linting: black src/ && flake8 src/
6. Commit with conventional commits: git commit -m "feat: add new feature"
7. Push and create a pull request

Code Quality Standards

• Code Coverage: Minimum 80% (target 85%+)
• Type Hints: Required for all public functions
• Documentation: Comprehensive docstrings for public APIs
• Performance: All changes must meet response time requirements
• Security: No credentials in logs, input validation required

📝 License

This project is licensed under the MIT License - see the file for details.

🏷️ Version History

• v0.1.0: Initial release with core parsing and MCP server functionality

🔧 Troubleshooting

Common Issues

Installation Problems:

# Python version issues
python --version  # Should be 3.9+

# Permission errors
pip install --user swagger-mcp-server

# Package conflicts
python -m venv venv && source venv/bin/activate

Runtime Issues:

# Port already in use
swagger-mcp-server serve --port 9000

# Database locked
swagger-mcp-server stop --all

# Search index corruption
rm -rf search_index/ && swagger-mcp-server serve

📖 Comprehensive Troubleshooting: See for detailed solutions to installation, configuration, and runtime problems.

📚 Complete Documentation

🚀 Getting Started

• - System requirements, installation methods, verification
• - 5-minute setup with sample API
• - Essential configuration for new users

📖 Reference Documentation

• - Complete command reference with examples
• - All configuration options and settings
• - Protocol documentation and client libraries

💡 Examples and Integrations

• - Realistic APIs for testing and learning
• - Environment-specific configurations
• - VS Code, Cursor, and custom integrations

🔧 Advanced Topics

• - Production deployment and scaling
• - Optimization and monitoring
• - Hardening and best practices

🆘 Support and Troubleshooting

• - Frequently encountered problems
• - Error messages and solutions
• - Debugging and analysis tools

🛠️ Development

• - Complete development environment setup
• - How to contribute to the project
• - Technical design and decisions

📖 Main Documentation Hub: See for the complete documentation index with detailed navigation.

🆘 Getting Help

Quick Help

• 🚀 New Users: Start with
• 🔧 Problems: Check
• ⚙️ Configuration: See
• 🤖 AI Integration: Follow

Community Support

• 🐛 Issues: GitHub Issues for bugs and feature requests
• 💬 Discussions: GitHub Discussions for questions and community support
• 📖 Documentation: with searchable content
• 💡 Examples: for common use cases

Before Reporting Issues

1. ✅ Check
2. ✅ Search existing issues
3. ✅ Try with
4. ✅ Include system info and logs in your report