# Specwise MCP

> Specwise MCP is a freemium MCP server for developer tools. Validate OpenAPI and JSON Schema and flag breaking changes between spec versions. It runs locally on your machine and is started by your AI client.

- **Kind:** MCP server
- **Pricing:** Freemium
- **Platforms:** CLI, API
- **Website:** https://specwise.bytestay.pt/integration.html
- **Repository:** https://github.com/bytestay/specwise-mcp
- **MCP Registry name:** io.github.Bytestay/specwise-mcp
- **Categories:** developer tools
- **Listing updated:** 2026-11-14

## About

Specwise can compare a spec file with its version at a git ref such as main, so an agent can check a change before opening a pull request. Diff results label each change breaking, warning, non-breaking or info and suggest a semver bump. Validation reports every error with its JSON Pointer, line and column, plus lint warnings, for OpenAPI 3.x and Swagger 2.0.

A third tool checks a JSON Schema against its meta-schema and, if given, data against the schema. Specs, schemas and data can be local file paths. It runs over stdio with uvx and a RapidAPI or api.market key.

## Features

- **Spec validation:** Errors with pointer, line and column.
- **Breaking-change diff:** Classifies each change and suggests a semver bump.
- **Git ref comparison:** Compares a file with its version on a branch.
- **Schema checks:** Validates schemas and data instances.
- **CI gate:** Gates on valid and breaking results.

## Good for

- Gate pull requests on breaking API changes
- Validate an OpenAPI file before commit
- Check JSON payloads against a schema
- Choose a semver bump for an API release

## Install

### Claude Code (Terminal)

```sh
claude mcp add specwise-mcp --env RAPIDAPI_KEY='<RAPIDAPI_KEY>' --env API_MARKET_KEY='<API_MARKET_KEY>' -- uvx bytestay-specwise-mcp
```

### Claude Desktop (claude_desktop_config.json)

```json
{
  "mcpServers": {
    "specwise-mcp": {
      "command": "uvx",
      "args": [
        "bytestay-specwise-mcp"
      ],
      "env": {
        "RAPIDAPI_KEY": "<RAPIDAPI_KEY>",
        "API_MARKET_KEY": "<API_MARKET_KEY>"
      }
    }
  }
}
```

### Cursor (~/.cursor/mcp.json)

```json
{
  "mcpServers": {
    "specwise-mcp": {
      "command": "uvx",
      "args": [
        "bytestay-specwise-mcp"
      ],
      "env": {
        "RAPIDAPI_KEY": "<RAPIDAPI_KEY>",
        "API_MARKET_KEY": "<API_MARKET_KEY>"
      }
    }
  }
}
```

### VS Code (.vscode/mcp.json)

```json
{
  "servers": {
    "specwise-mcp": {
      "type": "stdio",
      "command": "uvx",
      "args": [
        "bytestay-specwise-mcp"
      ],
      "env": {
        "RAPIDAPI_KEY": "<RAPIDAPI_KEY>",
        "API_MARKET_KEY": "<API_MARKET_KEY>"
      }
    }
  }
}
```

### Windsurf (~/.codeium/windsurf/mcp_config.json)

```json
{
  "mcpServers": {
    "specwise-mcp": {
      "command": "uvx",
      "args": [
        "bytestay-specwise-mcp"
      ],
      "env": {
        "RAPIDAPI_KEY": "<RAPIDAPI_KEY>",
        "API_MARKET_KEY": "<API_MARKET_KEY>"
      }
    }
  }
}
```

### Other clients (your client's MCP settings (most use this shape))

```json
{
  "mcpServers": {
    "specwise-mcp": {
      "command": "uvx",
      "args": [
        "bytestay-specwise-mcp"
      ],
      "env": {
        "RAPIDAPI_KEY": "<RAPIDAPI_KEY>",
        "API_MARKET_KEY": "<API_MARKET_KEY>"
      }
    }
  }
}
```

## Tools

- `validate_openapi`: Every error with its JSON Pointer, line and column, plus lint warnings.
- `diff_openapi`: Each change between two OpenAPI 3.x versions as breaking, warning, non-breaking or info, with a semver suggestion.
- `validate_json_schema`: Checks a schema against its meta-schema and, if given, data against the schema.

## FAQ

### Which spec versions?

OpenAPI 3.x and Swagger 2.0 for validation; OpenAPI 3.x for diffs.

### Can it compare against a branch?

Yes, diff_openapi accepts a git ref such as main.

### What keys are needed?

RapidAPI or api.market.

### Free?

Basic is free on RapidAPI at 15 requests a month.

### Is Specwise MCP free?

Specwise MCP has a free plan, with paid plans for more usage or features.

### How do I add Specwise MCP to Claude Code?

Run this command in your terminal: claude mcp add specwise-mcp --env RAPIDAPI_KEY='<RAPIDAPI_KEY>' --env API_MARKET_KEY='<API_MARKET_KEY>' -- uvx bytestay-specwise-mcp

### What are the best alternatives to Specwise MCP?

The closest alternatives to Specwise MCP are REA, Codebase Memory, GitHub, Serena MCP: the IDE for your agent and XERJ.

## Alternatives

- [REA](https://ai-powered.com/mcp/rea): REA is an open-source MCP server for developer tools.
- [Codebase Memory](https://ai-powered.com/mcp/codebase-memory): Codebase Memory is an open-source MCP server for knowledge and memory.
- [GitHub](https://ai-powered.com/mcp/github-2): GitHub is an open-source MCP server for developer tools.
- [Serena MCP: the IDE for your agent](https://ai-powered.com/mcp/serena-mcp-the-ide-for-your-agent): Serena MCP: the IDE for your agent is an open-source MCP server for developer tools.
- [XERJ](https://ai-powered.com/mcp/xerj): XERJ is an open-source MCP server for knowledge and memory.
- [Ouroboros](https://ai-powered.com/mcp/ouroboros): Ouroboros is an open-source MCP server for developer tools.
- [Claude Code Ultimate Guide](https://ai-powered.com/mcp/claude-code-ultimate-guide): Claude Code Ultimate Guide is an open-source MCP server for ai models and llm tooling.
- [Concord MCP](https://ai-powered.com/mcp/concord-mcp): Concord MCP is a freemium MCP server for developer tools.

---
Source: https://ai-powered.com/mcp/specwise-mcp
