OpenAPI Analyzer MCP server for AI agents

The OpenAPI Analyzer MCP Server enables natural language queries about API structures through Claude Desktop and other LLM clients. It helps you analyze OpenAPI specifications, search across endpoints, and identify inconsistencies across multiple API specs.

Installation

From npm

npm install openapi-analyzer-mcp

From source

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

Configuration

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

API Registry (OPENAPI_DISCOVERY_URL)
Individual URLs (OPENAPI_SPEC_URLS)
Local Folder (OPENAPI_SPECS_FOLDER)

Claude Desktop Setup

Find your config file at:

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

Configuration Examples

API Registry Discovery (Recommended)

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

Individual API 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"
      }
    }
  }
}

Local Folder

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

Multi-Source with 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"
      }
    }
  }
}

Environment Variables

Variable	Description	Example	Priority
`OPENAPI_DISCOVERY_URL`	URL to API registry (apis.json format)	`https://docs.company.com/apis.json`	1 (Highest)
`OPENAPI_SPEC_URLS`	Comma-separated list of OpenAPI spec URLs	`https://api1.com/spec.yaml,https://api2.com/spec.json`	2 (Medium)
`OPENAPI_SPECS_FOLDER`	Absolute path to local OpenAPI files folder	`/absolute/path/to/specs`	3 (Fallback)

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

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

Available Tools

Tool	Description	Parameters
`load_specs`	Smart Load: Automatically load specs using priority system	None
`list_apis`	List all loaded APIs with basic info	None
`get_api_spec`	Get the full OpenAPI spec for a specific file	`filename`
`search_endpoints`	Search endpoints by keyword across all APIs	`query`
`get_api_stats`	Generate comprehensive statistics about all loaded APIs	None
`find_inconsistencies`	Detect inconsistencies in authentication schemes	None
`compare_schemas`	Compare schemas with the same name across different APIs	`schema1`, `schema2` (optional)
`get_load_sources`	Show where specs were loaded from	None

Creating Your Own API Registry

Standard APIs.json Format

Create a file at https://your-domain.com/apis.json:

{
  "name": "Your Company APIs",
  "description": "Collection of all our API specifications",
  "url": "https://your-domain.com",
  "apis": [
    {
      "name": "User API",
      "baseURL": "https://api.your-domain.com/users",
      "properties": [
        {
          "type": "Swagger",
          "url": "https://docs.your-domain.com/user-api.yaml"
        }
      ]
    },
    {
      "name": "Orders API", 
      "baseURL": "https://api.your-domain.com/orders",
      "properties": [
        {
          "type": "OpenAPI",
          "url": "https://docs.your-domain.com/orders-api.json"
        }
      ]
    }
  ]
}

Custom Registry Format

Or use the simpler custom format:

{
  "name": "Your Company APIs",
  "description": "Our API registry",
  "apis": [
    {
      "name": "User API",
      "version": "v2",
      "spec_url": "https://docs.your-domain.com/user-api.yaml",
      "docs_url": "https://docs.your-domain.com/user-api",
      "status": "stable",
      "tags": ["auth", "users"]
    }
  ]
}

Troubleshooting

Tools not appearing in Claude Desktop

Verify environment variables are set - At least one source must be configured
Check that URLs are accessible - Test discovery URLs and spec URLs manually
Restart Claude Desktop completely after configuration changes
Check network connectivity for remote API registries
Verify file formats - Supports JSON, YAML, and YML

Debug Mode

Set NODE_ENV=development to see detailed logging:

{
  "mcpServers": {
    "openapi-analyzer": {
      "command": "node",
      "args": ["/path/to/dist/index.js"],
      "env": {
        "OPENAPI_SPECS_FOLDER": "/path/to/specs",
        "NODE_ENV": "development"
      }
    }
  }
}

How to install this MCP server

For Claude Code

To add this MCP server to Claude Code, run this command in your terminal:

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

See the official Claude Code MCP documentation for more details.

For Cursor

There are two ways to add an MCP server to Cursor. The most common way is to add the server globally in the ~/.cursor/mcp.json file so that it is available in all of your projects.

If you only need the server in a single project, you can add it to the project instead by creating or adding it to the .cursor/mcp.json file.

Adding an MCP server to Cursor globally

To add a global MCP server go to Cursor Settings > Tools & Integrations and click "New MCP Server".

When you click that button the ~/.cursor/mcp.json file will be opened and you can add your server like this:

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

Adding an MCP server to a project

To add an MCP server to a project you can create a new .cursor/mcp.json file or add it to the existing one. This will look exactly the same as the global MCP server example above.

How to use the MCP server

Once the server is installed, you might need to head back to Settings > MCP and click the refresh button.

The Cursor agent will then be able to see the available tools the added MCP server has available and will call them when it needs to.

You can also explicitly ask the agent to use the tool by mentioning the tool name and describing what the function does.

For Claude Desktop

To add this MCP server to Claude Desktop:

1. Find your configuration file:

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

2. Add this to your configuration file:

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

3. Restart Claude Desktop for the changes to take effect