mcpField
M
MCP Spectral

MCP Spectral

Local
github.com/mark-sivillDeveloper Tools1Updated 69w ago
Repository

About MCP Spectral

MCP Spectral wraps the Spectral CLI in Docker as an MCP server for LLMs checking OpenAPI specifications. It provides specification linting, ruleset-based linting, and a Spectral version query.

Key features

  1. 01Lint OpenAPI specifications
  2. 02Lint with a specified ruleset
  3. 03Query the Spectral version
  4. 04Run through Docker

Use cases

  1. 01Find issues in an OpenAPI specification
  2. 02Validate API definitions against team rules
  3. 03Check the active Spectral version

MCP support

It exposes OpenAPI linting and Spectral version tools to MCP clients, allowing LLMs to run Spectral checks.

#mcp-spectral#openapi#linting

Configuration

Local server config is the same for every client. Copy it into your client’s MCP config file.

mcp.json · Universal config
{
  "mcpServers": {
    "spectral": {
      "command": "docker",
      "args": [
        "run",
        "-i",
        "--rm",
        "marksivill/mcp-spectral"
      ]
    }
  }
}
Run commanddocker run -i --rm marksivill/mcp-spectral

Local servers need a runtime on your machine (e.g. Node.js 18+). Config file locations differ by client; see your client’s docs.

Packages
ocimarksivill/mcp-spectral

Tools

No tool list yet

Local servers expose tools only once running on your machine, and the maintainer has not provided a tool list.

Details

From the project README

MCP Spectral

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

Overview

Allow Large Language Models (LLM) to check whether an OpenAPI Specifications is valid using a Model Context Protocol (MCP) Server.

The MCP Spectral Server wrappers the Spectral command line within a Docker image.

Using an OpenAPI specification to describe an API provides consistency across APIs, the ability to document the API, a contract on how to use the API, the ability to generate code stubs to consume and produce APIs, and API versioning. These features enable quicker API development, quicker uptake of API services, and a reduction in API maintenance.

Using MCP Spectral should reduce API development time further by helping with the OpenAPI specification phase.

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

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

Local builds

Optionally the docker image can be built locally instead of pulling from Docker Hub using

docker build --tag marksivill/mcp-spectral:latest .

This is useful if the source code or default ruleset needs to be changed for example

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

Comments

Markdown supported

New to MCP?

From what the protocol is to installing your first server, these answers cover most first questions.

An open protocol that defines how AI applications connect to external tools and data in a uniform way. Clients talk to the model; MCP servers provide tools, resources and prompt templates. They exchange standard messages, so one server can be reused by many clients.