MCP Spectral Server

Model Context Protocol (MCP) Server for Spectral to lint OpenAPI specifications

Available tools

Tools provided by MCP Spectral

• lint_openapi - lints OpenAPI specification
• lint_openapi_with_ruleset - lints OpenAPI specification with Spectral ruleset
• spectral_version - returns version of Spectral being used

Set up instructions

These instruction assume Anthropic Claude Desktop will interact with the MCP Spectral server. If another Large Language Model tool is being used change the set up instructions accordlingly.

Installation prerequisites

Ensure the following applications are installed on the local machine

• Claude Desktop install
• Docker install

Update Claude Desktop

Add following to the claude_desktop_config.json file within the Claude Desktop installation which tells Claude Desktop how to access MCP Spectral

{
  "mcpServers": {
    "OpenAPI linting (Spectral)": {
      "command": "docker",
      "args": [
        "run",
        "-i",
        "--rm",
        "marksivill/mcp-spectral"
      ]
    }
  }
}

For example if MCP Spectral is also installed with mcp/fetch the complete claude_desktop_config.json would be

{
  "mcpServers": {
    "fetch": {
      "command": "docker",
      "args": [
        "run",
        "-i",
        "--rm",
        "mcp/fetch"
      ]
    },
    "OpenAPI linting (Spectral)": {
      "command": "docker",
      "args": [
        "run",
        "-i",
        "--rm",
        "marksivill/mcp-spectral"
      ]
    }
  }
}

Once the file has been updated, restart the Claude Desktop.

Claude Desktop will automatically pull the latest docker version of MCP Spectral from Docker Hub

Example Claude Desktop prompts

Below are example prompts for Claude Desktop which may also work in other Large Language Model (LLM) tools that are calling MCP Spectral.

Note mcp/fetch may also need to be installed into Claude Desktop to fetch URLs.

Prompt 1

What version of Spectral do we have access to

Prompt 2

Validate the OpenAPI specification from OpenWeatherMap API.
If any errors are found, fix them, then revalidate, repeat the last steps until the OpenAPI specification is valid.

Prompt 3

Using the API documentation found at https://wheretheiss.at/w/developer build an OpenAPI specification.
Ensure that there are no validation errors.
If any errors are found, fix them, then revalidate, repeat the last steps until the OpenAPI specification is valid.

Prompt 4

Build an OpenAPI specification version 3.1 for the Rick and Morty API.
Ensure that there are no validation errors.
If any errors are found, fix them, then revalidate, repeat the last steps until the OpenAPI specification is valid.

Prompt 5

Using the API documentation found at https://wheretheiss.at/w/developer build an OpenAPI specification version 3.1 using the rules
1) ensure all operationIds use kebab case
2) add info and contact information using your details
3) ensure servers are defined
4) ensure all operations contains a description
5) ensure all operations have one or more relevant tags
6) ensure there is a tag section

Ensure that there are no validation errors.
If any errors are found, fix them, then revalidate, repeat the last steps until the OpenAPI specification is valid.

Useful links

• What is an MCP Server?⁠
• MCP Spectral on Docker Hub
• Spectral linter for OpenAPI specifications