OpenAPI Analyzer MCP Server

A powerful Model Context Protocol (MCP) server for analyzing OpenAPI specifications with Claude Desktop and other LLM clients. This server enables natural language queries about your API structures, endpoints, schemas, and helps identify inconsistencies across multiple OpenAPI specs.

📋 Table of Contents

• 🚀 Features
• 🛠 Installation
• ⚙️ Configuration
• 🎯 Usage
• 🔧 Available Tools
• 🔍 Example Output
• 🏗️ Creating Your Own API Registry
• 🚨 Troubleshooting
• 🤝 Contributing
• 🆕 Changelog
• 📝 License

🚀 Features

🎯 Smart Discovery System

• 📡 API Registry Support: Automatically discover APIs from apis.json registries (support for 30+ APIs)
• 🔗 URL-Based Loading: Load specs from individual URLs with automatic fallback
• 📁 Local File Support: Traditional folder-based spec loading with multi-format support
• 🔄 Priority System: Discovery URL → Individual URLs → Local folder (intelligent fallback)

🔍 Advanced Analysis

• 📊 Bulk Analysis: Load and analyze 90+ OpenAPI specification files simultaneously
• 🔍 Smart Search: Find endpoints across all APIs using natural language queries
• 📈 Comprehensive Stats: Generate detailed statistics about your API ecosystem
• 🔧 Inconsistency Detection: Identify authentication schemes and naming convention mismatches
• 📋 Schema Comparison: Compare schemas with the same name across different APIs
• ⚡ Fast Queries: In-memory indexing for lightning-fast responses

🌐 Universal Compatibility

• Multi-Format Support: JSON, YAML, and YML specifications
• Version Support: OpenAPI 2.0, 3.0, and 3.1 specifications
• Remote & Local: Works with URLs, API registries, and local files
• Source Tracking: Know exactly where each API spec was loaded from

🛠 Installation

Option 1: Install from npm

npm install openapi-analyzer-mcp

Option 2: Build from source

git clone https://github.com/sureshkumars/openapi-analyzer-mcp.git
cd openapi-analyzer-mcp
npm install
npm run build

⚙️ Configuration

🎯 Smart Discovery Options

The OpenAPI Analyzer supports three discovery methods with intelligent priority fallback:

1. 🏆 Priority 1: API Registry (OPENAPI_DISCOVERY_URL)
2. 🥈 Priority 2: Individual URLs (OPENAPI_SPEC_URLS)
3. 🥉 Priority 3: Local Folder (OPENAPI_SPECS_FOLDER)

Claude Desktop Setup

Find your config file:

• macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
• Windows: %APPDATA%\Claude\claude_desktop_config.json

Configuration Examples

🌟 Option 1: API Registry Discovery (Recommended)

Perfect for companies with centralized API registries:

{
  "mcpServers": {
    "openapi-analyzer": {
      "command": "npx",
      "args": ["-y", "openapi-analyzer-mcp"],
      "env": {
        "OPENAPI_DISCOVERY_URL": "https://docs.company.com/apis.json"
      }
    }
  }
}

🔗 Option 2: Individual API URLs

Load specific APIs from direct URLs:

{
  "mcpServers": {
    "openapi-analyzer": {
      "command": "npx", 
      "args": ["-y", "openapi-analyzer-mcp"],
      "env": {
        "OPENAPI_SPEC_URLS": "https://api.example.com/v1/openapi.yaml,https://api.example.com/v2/openapi.yaml,https://petstore.swagger.io/v2/swagger.json"
      }
    }
  }
}

📁 Option 3: Local Folder

Traditional approach for local specification files:

{
  "mcpServers": {
    "openapi-analyzer": {
      "command": "npx",
      "args": ["-y", "openapi-analyzer-mcp"],
      "env": {
        "OPENAPI_SPECS_FOLDER": "/absolute/path/to/your/openapi-specs"
      }
    }
  }
}

🔄 Option 4: Multi-Source with Fallback

Ultimate flexibility - tries all methods with intelligent fallback:

{
  "mcpServers": {
    "openapi-analyzer": {
      "command": "npx",
      "args": ["-y", "openapi-analyzer-mcp"],
      "env": {
        "OPENAPI_DISCOVERY_URL": "https://docs.company.com/apis.json",
        "OPENAPI_SPEC_URLS": "https://legacy-api.com/spec.yaml,https://external-api.com/spec.json",
        "OPENAPI_SPECS_FOLDER": "/path/to/local/specs"
      }
    }
  }
}

🏢 Real-World Examples

Company with API Registry:

{
  "mcpServers": {
    "company-apis": {
      "command": "npx",
      "args": ["-y", "openapi-analyzer-mcp"],
      "env": {
        "OPENAPI_DISCOVERY_URL": "https://api.company.com/registry/apis.json"
      }
    }
  }
}

Multiple API Sources:

{
  "mcpServers": {
    "multi-apis": {
      "command": "npx",
      "args": ["-y", "openapi-analyzer-mcp"],
      "env": {
        "OPENAPI_SPEC_URLS": "https://petstore.swagger.io/v2/swagger.json,https://api.example.com/v1/openapi.yaml"
      }
    }
  }
}

🔧 Environment Variables

⚠️ Important Notes:

• At least one environment variable must be set
• System tries sources in priority order and stops at first success
• Always use absolute paths for OPENAPI_SPECS_FOLDER
• Supports JSON, YAML, and YML formats for all sources

🎯 Usage

Once configured, you can interact with your OpenAPI specs using natural language in Claude Desktop:

🚀 Smart Discovery Queries

API Registry Discovery

"Load all APIs from the company registry and show me an overview"
"Discover APIs from the configured registry and analyze their authentication patterns"
"What APIs are available in our API registry?"
"Show me where my specs were loaded from"

Cross-API Analysis

"Load all my OpenAPI specs and give me a comprehensive summary"
"How many APIs do I have and what's the total number of endpoints?"
"Compare authentication schemes across all loaded APIs"
"Which APIs are using different versions of the same schema?"

Search and Discovery

"Show me all POST endpoints for user creation across all APIs"
"Find all endpoints related to authentication across all loaded APIs"
"Which APIs have pagination parameters?"
"Search for endpoints that handle file uploads"
"Find all APIs that use the 'User' schema"

Analysis and Comparison

"What authentication schemes are used across my APIs?"
"Which APIs have inconsistent naming conventions?"
"Compare the User schema across different APIs"
"Show me APIs that are still using version 1.0"

Statistics and Insights

"Generate comprehensive statistics about my API ecosystem"
"Which HTTP methods are most commonly used?"
"What are the most common path patterns?"
"Show me version distribution across my APIs"

🔧 Available Tools

The MCP server provides these tools for programmatic access:

📁 Project Structure

openapi-analyzer-mcp/
├── src/
│   └── index.ts          # Main server implementation
├── tests/               # Comprehensive test suite
│   ├── analyzer.test.ts # Core functionality tests
│   ├── server.test.ts   # MCP server tests  
│   ├── validation.test.ts # Environment tests
│   ├── setup.ts         # Test configuration
│   └── fixtures/        # Test data files
├── dist/                # Compiled JavaScript
├── coverage/            # Test coverage reports
├── examples/            # Example configurations
│   ├── claude_desktop_config.json
│   └── sample-openapi.json
├── vitest.config.ts     # Test configuration
├── package.json
├── tsconfig.json
└── README.md

Note: You don't need an openapi-specs folder in this repository. Point OPENAPI_SPECS_FOLDER to wherever your actual OpenAPI files are located.

🔍 Example Output

🎯 Smart Discovery Results

Load Sources Information

[
  {
    "type": "discovery",
    "url": "https://api.company.com/registry/apis.json",
    "count": 12,
    "metadata": {
      "name": "Company APIs",
      "description": "Collection of company API specifications",
      "total_apis": 12
    }
  }
]

Registry Discovery Success

{
  "totalApis": 12,
  "totalEndpoints": 247,
  "loadedFrom": "API Registry",
  "discoveryUrl": "https://api.company.com/registry/apis.json",
  "apis": [
    {
      "filename": "User Management API",
      "title": "User Management API", 
      "version": "2.1.0",
      "endpointCount": 18,
      "source": "https://docs.company.co

---