The problem
Upgrading a Rails app from one version to the next means figuring out what changed in the default rails new output. You end up tabbing between RailsDiff in the browser, copying file names, and pasting diffs back into your editor. If you are using an AI agent to help with the upgrade, it cannot access that information on its own - you become the middleman.
What Rails Diff MCP does
Rails Diff MCP is an MCP server that gives your AI agent direct access to Rails version diffs. The data comes from the railsdiff/rails-new-output repository, where each Rails version is tagged with the output of rails new.
The server exposes three tools:
| Tool | Description |
|---|---|
list_rails_versions | List all available Rails versions (sorted) |
compare_rails_versions | Compare two versions - returns a list of changed files |
get_file_diff | Get the patch for a specific file between two versions |
Instead of looking up diffs yourself, you tell the agent "upgrade this app from 8.0.1 to 8.0.2" and it can inspect every changed file on its own.
Setup
The server runs via Docker Compose:
docker compose up -dIt listens on http://localhost:8080/mcp with a health check at http://localhost:8080/healthz.
Register it in Claude Code:
claude mcp add --transport http rails-diff http://localhost:8080/mcpOptionally set a GITHUB_TOKEN environment variable to avoid GitHub API rate limits.
How an upgrade workflow looks
Once the MCP server is running and registered, a Rails upgrade conversation might go like this:
- Ask the agent to compare your current Rails version with the target version
- The agent calls
compare_rails_versionsand gets the list of changed files - For each relevant file, it calls
get_file_diffto see the exact patch - It applies the changes to your project, adapting them to your existing configuration
No browser tabs, no copy-pasting diffs, no back-and-forth.
Credits
Built on top of RailsDiff by Andy Stewart and contributors.
The source code is on GitHub.