OpenAPI Documentation MCP server

This MCP server provides tools for managing and retrieving OpenAPI documentation, allowing you to list API groups, explore APIs within a group, get detailed API information, and search through available APIs.

Installation

You can quickly run the MCP server using npx without installing it permanently. The server can work with both remote API documentation URLs and local JSON files.

# For remote API documentation
npx -y api-doc-mcp http://localhost:8000/swagger.json

# For local JSON files
npx -y api-doc-mcp ./swagger.json

Usage Guide

Basic Command Format

The basic command format for using the MCP server is:

npx api-doc-mcp <API_DOC_URL_OR_FILE_PATH>

Available Commands

Viewing Help

To view the help information and available commands:

npx api-doc-mcp

Working with API Groups

To list all available API groups from a remote API:

npx api-doc-mcp https://api.example.com/swagger.json

To list API groups from a local Swagger/OpenAPI file:

npx api-doc-mcp ./swagger.json

Tool Functionality

The MCP server provides several key functions to help you work with API documentation:

List API Groups

The listApiGroups function shows all available API groups with the following information:

• Group name
• Group description
• Number of APIs in the group

List APIs in a Group

Use listGroupApis to see all APIs within a specific group:

Parameter: groupName

This returns:

• API path
• HTTP method
• API summary

Get API Details

To retrieve comprehensive information about a specific API endpoint:

Parameters: 
- path
- method

This returns complete API details including:

• Parameters
• Request body structure
• Response definition

Search APIs

The search function helps you find specific APIs by keyword:

Parameter: keyword

Results include:

• API path
• HTTP method
• API summary

Features

The MCP server includes these helpful features:

• Support for both remote API documentation and local JSON files
• Automatic refresh of API documentation on each request
• Comprehensive API exploration tools
• Search capability across all available APIs

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 "api-doc-mcp" '{"command":"npx","args":["-y","api-doc-mcp","${input}"]}'

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": {
        "api-doc-mcp": {
            "command": "npx",
            "args": [
                "-y",
                "api-doc-mcp",
                "${input}"
            ]
        }
    }
}

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": {
        "api-doc-mcp": {
            "command": "npx",
            "args": [
                "-y",
                "api-doc-mcp",
                "${input}"
            ]
        }
    }
}

3. Restart Claude Desktop for the changes to take effect