breaking-changes-mcp

Stop your coding agent from hallucinating dependency migrations.

An MCP server that gives Claude, Cursor, and any MCP client accurate, source-grounded breaking-change briefings for any npm package — read straight from the real GitHub release notes and CHANGELOG, not from the model's stale training data.

LLMs are great at writing code and terrible at remembering exactly what changed between react@18 and react@19, or next@14 and next@16. That's where upgrades break. This server closes the gap: point it at a package and a version range, and the agent gets the actual breaking changes before it touches your code.

Why this exists

Tools like Context7 inject current docs. But the most dangerous moment for an agent is a version bump, and nobody serves the delta between two versions. breaking-changes-mcp is that missing piece.

Tools

Tool	What it does
breaking_changes_between	The headline tool. Returns only the breaking changes for a package between two versions, grouped per version, newest first. Reads GitHub Releases, falls back to CHANGELOG.md.
changelog_between	The full release notes (features, fixes, deprecations) across a version range — when breaking-only isn't enough.
list_versions	Published versions + release dates, newest first — to discover valid from/to values.

Every tool works on the public npm registry + GitHub with no API key required. Set GITHUB_TOKEN to raise GitHub's rate limit from 60 to 5000 requests/hour.

Quick start

npx breaking-changes-mcp

Claude Code

claude mcp add breaking-changes -- npx -y breaking-changes-mcp
# optional: higher GitHub rate limit
claude mcp add breaking-changes -e GITHUB_TOKEN=ghp_xxx -- npx -y breaking-changes-mcp

Claude Desktop / Cursor / Windsurf / any MCP client

{
  "mcpServers": {
    "breaking-changes": {
      "command": "npx",
      "args": ["-y", "breaking-changes-mcp"],
      "env": { "GITHUB_TOKEN": "ghp_xxx_optional" }
    }
  }
}

Example prompts

• "I'm on react 18.2.0 and want to go to 19. Use breaking-changes to tell me exactly what will break."
• "Before you upgrade next in this repo, check the breaking changes between the installed version and latest."
• "Give me the full changelog for @tanstack/react-query from 4.0.0 to 5.0.0."

Config

Env var	Default	Purpose
GITHUB_TOKEN / GH_TOKEN	—	Personal access token to raise GitHub API limits (60→5000/hr). Read-only, no scopes needed for public repos.
NPM_REGISTRY	https://registry.npmjs.org	Override for private/mirror registries.

How it works

package + from..to
   │
   ├─ npm registry ──► all versions, dates, repository URL
   ├─ versions in (from, to]
   ├─ GitHub Releases ──► release bodies for those versions
   │        └─ fallback: raw CHANGELOG.md sliced between version headers
   └─ extract "### Breaking…" sections + "BREAKING CHANGE" lines ──► grouped briefing

Develop

npm install
npm run build
node dist/index.js   # speaks MCP over stdio

Caveats

• Quality of output depends on the maintainer documenting breaking changes. If a project buries them in prose, breaking_changes_between says so and points you to changelog_between.
• Monorepo tags (pkg@1.2.3) and prefixed tags (v1.2.3, release-1.2.3) are handled; exotic tag schemes may miss.

License

MIT © Anicodeth