🚀 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.
💡 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)
- Visit any API documentation website (e.g.,
docs.example.com/api) - Open Browser DevTools (
F12orCmd/Ctrl + Shift + I) - Go to Network tab and refresh the page
- Look for
swagger.jsonor similar files in the network requests - Click on the JSON file and copy the response
- 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
# Install Poetry
pipx install poetry
Local Development
-
Clone and setup:
git clone https://github.com/salacoste/openapi-mcp-swagger.git cd openapi-mcp-swagger -
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 shellOption 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 -
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!') " -
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 -
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 docs/api/MCP_PROTOCOL.md 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 docs/reference/CLI_REFERENCE.md 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 docs/guides/PERFORMANCE.md 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 docs/examples/integrations/ 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: docs/examples/configurations/development.yaml
- Production: docs/examples/configurations/production.yaml
📖 Configuration Guide: See docs/guides/BASIC_CONFIG.md for configuration basics and docs/reference/CONFIGURATION.md for complete reference.
💡 Examples
Sample APIs
We provide realistic sample APIs for testing:
- E-commerce Platform (45 endpoints): docs/examples/swagger-files/ecommerce-api.json
- Banking API (67 endpoints): docs/examples/swagger-files/banking-api.json
- Healthcare API (52 endpoints): docs/examples/swagger-files/healthcare-api.json
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 docs/examples/swagger-files/README.md for all available sample APIs and use cases.
🤝 Contributing
We welcome contributions! Please see our contribution guidelines for details.
Development Workflow
- Fork the repository
- Create a feature branch:
git checkout -b feat/my-feature - Make your changes with tests
- Run the test suite:
pytest - Run linting:
black src/ && flake8 src/ - Commit with conventional commits:
git commit -m "feat: add new feature" - 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 LICENSE 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 docs/troubleshooting/COMMON_ISSUES.md for detailed solutions to installation, configuration, and runtime problems.
📚 Complete Documentation
🚀 Getting Started
- Installation Guide - System requirements, installation methods, verification
- Quick Start Tutorial - 5-minute setup with sample API
- Basic Configuration - Essential configuration for new users
📖 Reference Documentation
- CLI Reference - Complete command reference with examples
- Configuration Reference - All configuration options and settings
- MCP Protocol API - Protocol documentation and client libraries
💡 Examples and Integrations
- Sample APIs - Realistic APIs for testing and learning
- Configuration Templates - Environment-specific configurations
- AI Tool Integrations - VS Code, Cursor, and custom integrations
🔧 Advanced Topics
- Deployment Guide - Production deployment and scaling
- Performance Tuning - Optimization and monitoring
- Security Configuration - Hardening and best practices
🆘 Support and Troubleshooting
- Common Issues - Frequently encountered problems
- Error Reference - Error messages and solutions
- Diagnostic Tools - Debugging and analysis tools
🛠️ Development
- Development Setup - Complete development environment setup
- Contributing Guide - How to contribute to the project
- Architecture Documentation - Technical design and decisions
📖 Main Documentation Hub: See docs/README.md for the complete documentation index with detailed navigation.
🆘 Getting Help
Quick Help
- 🚀 New Users: Start with Quick Start Tutorial
- 🔧 Problems: Check Common Issues
- ⚙️ Configuration: See Basic Configuration
- 🤖 AI Integration: Follow Integration Guides
Community Support
- 🐛 Issues: GitHub Issues for bugs and feature requests
- 💬 Discussions: GitHub Discussions for questions and community support
- 📖 Documentation: Complete docs with searchable content
- 💡 Examples: Working examples for common use cases
Before Reporting Issues
- ✅ Check Common Issues
- ✅ Search existing issues
- ✅ Try with minimal configuration
- ✅ Include system info and logs in your report
🌟 Show Your Support 🌟
If this project helped solve your API integration challenges, please consider starring it!
🎯 Why your star matters:
- 📈 Increases visibility for developers facing similar challenges
- 💪 Motivates continued development and new features
- 🚀 Helps us prioritize community-requested improvements
- 🤝 Shows appreciation for open-source work
Quick Actions:
⭐ Star • 🍴 Fork • 📋 Issues • 💬 Discuss
Thank you for being part of our community! 🙏