Unified Diff MCP Server

![smithery badge](https://smithery.ai/server/@gorosun/unified-diff-mcp)

Beautiful diff visualization for Claude Desktop. Transform code diffs into stunning visual comparisons with GitHub Gist integration and local file output.

✨ Features

🎨 Beautiful HTML diff visualization using diff2html
🌐 GitHub Gist integration for instant sharing
📁 Local file output (PNG/HTML)
🔄 Auto-delete functionality for temporary diffs
🖥️ Cross-platform support (Windows, macOS, Linux)
⚡ High-performance with Bun runtime
🛡️ Enhanced Security with multi-level protection for shared diffs
🔒 Multi-level security (Low/Medium/High) for different use cases

🚀 Quick Start

Installing via Smithery

bunx @smithery/cli install @gorosun/unified-diff-mcp --client claude --config '{
  "defaultAutoOpen": true,
  "defaultOutputMode": "html",
  "githubUsername": "your_actual_github_username",
  "githubToken": "ghp_your_actual_token_here"
}'

Manual Installation

Install Claude Desktop and Bun
Clone and build:

   git clone https://github.com/gorosun/unified-diff-mcp.git
   cd unified-diff-mcp
   bun install

Configure Claude Desktop - see Configuration below

🛠️ Tools Overview

| Tool | Purpose | Output | Best For | |------|---------|--------|----------| | visualize_diff_html_content | Browser display & sharing | GitHub Gist + HTML preview URL | Quick sharing, instant viewing | | visualize_diff_output_file | Local file storage | PNG/HTML files | Local storage, presentations |

📖 Usage Examples

🎯 Optimal Prompts by Purpose

| Purpose | Recommended Prompt | Tool Used | Output | |---------|-------------------|-----------|--------| | Quick Preview | Please visualize and preview the following diff: 以下のdiffを可視化してプレビューしてください | visualize_diff_html_content | GitHub Gist + HTML preview URL | | Local Storage | Please visualize and save the following diff to a file: 以下のdiffを可視化してファイルに保存してください | visualize_diff_output_file | Local HTML/PNG file | | Share with Others | Please visualize the following diff and create a shareable link: 以下のdiffを可視化して共有リンクを作成してください | visualize_diff_html_content | GitHub Gist with shareable URL | | Image Export | Please visualize and save the following diff as a PNG image: 以下のdiffを可視化してPNG画像で保存してください | visualize_diff_output_file | Local PNG image | | Code Review | Please visualize the following diff in side-by-side format: 以下のdiffをside-by-side形式で可視化してください | Either tool | Side-by-side comparison | | Documentation | Please visualize and save the following diff as an HTML file: 以下のdiffを可視化してHTMLファイルで保存してください | visualize_diff_output_file | Local HTML file | | 🔒 Secure Sharing | Please visualize this diff with high security: 以下のdiffを高セキュリティで可視化してください | visualize_diff_html_content | Secret Gist with auto-delete |

Share diff instantly (GitHub Gist)

visualize_diff_html_content:
- Creates temporary GitHub Gist
- Auto-deletes after 30 minutes
- Instant browser-ready URLs
- Perfect for code reviews

Save diff locally

visualize_diff_output_file:
- Saves PNG or HTML to local disk
- Auto-opens in browser (optional)
- Perfect for documentation

🎛️ Configuration

Environment Variables

| Variable | Description | Default | |----------|-------------|---------| | GITHUB_TOKEN | GitHub Personal Access Token (for Gist integration) | Required for visualize_diff_html_content | | DEFAULT_AUTO_OPEN | Auto-open generated files | false | | DEFAULT_OUTPUT_MODE | Default output format (html or image) | html |

GitHub Token Setup

Go to GitHub Settings > Personal Access Tokens
Generate new token with gist scope
Add to your environment:

   export GITHUB_TOKEN="your_token_here"

Claude Desktop Configuration

macOS: ``bash code ~/Library/Application\ Support/Claude/claude_desktop_config.json ``

Windows: ``bash code %APPDATA%\Claude\claude_desktop_config.json ``

Configuration template: ``json { "mcpServers": { "unified-diff-mcp": { "command": "bun", "args": ["run", "/path/to/unified-diff-mcp/src/index.ts"], "env": { "GITHUB_TOKEN": "your_github_token_here", "DEFAULT_AUTO_OPEN": "true", "DEFAULT_OUTPUT_MODE": "html" } } } } ``

📋 Parameters Reference

Common Parameters

| Parameter | Type | Default | Description | |-----------|------|---------|-------------| | diff | string | (required) | Unified diff text | | format | string | side-by-side | Display format (line-by-line or side-by-side) | | showFileList | boolean | true | Show file list summary | | highlight | boolean | true | Enable syntax highlighting | | oldPath | string | file.txt | Original file path | | newPath | string | file.txt | Modified file path | | autoOpen | boolean | false | Auto-open in browser |

GitHub Gist Specific

| Parameter | Type | Default | Description | |-----------|------|---------|-------------| | expiryMinutes | number | 30 | Auto-delete time (1-1440 minutes) | | public | boolean | false | Public vs secret gist |

Local File Specific

| Parameter | Type | Default | Description | |-----------|------|---------|-------------| | outputType | string | html | Output format (html or image) |

🌍 Platform Support

| Platform | Auto-Open | Commands | |----------|-----------|----------| | Windows | ✅ | start (primary), explorer (fallback) | | macOS | ✅ | open (primary), AppleScript (fallback) | | Linux | ✅ | xdg-open |

🔧 Development

Development mode (with hot reload): ``json { "command": "bun", "args": ["--watch", "/path/to/unified-diff-mcp/src/index.ts"] } ``

Production mode: ``json { "command": "bun", "args": ["run", "/path/to/unified-diff-mcp/src/index.ts"] } ``

📚 Advanced Usage

🔒 Enhanced Security Levels

When GitHub Token isn't available or for secure sharing, you can choose from multiple security levels:

| Security Level | Configuration | Features | Use Cases | |---------|---------|--------|--------| | 🟢 Low | Secret Gist + 60min auto-delete | URL-only access | Code examples, learning | | 🟡 Medium | Secret Gist + Password + 30min auto-delete | URL + Access code required | Team reviews | | 🔴 High | Secret Gist + Password + 15min auto-delete | URL + Access code + Short duration | Sensitive code |

Usage Example

Please visualize this diff with high security:
--- a/config.js
+++ b/config.js
@@ -1,3 +1,4 @@
 const config = {
-  apiKey: 'old-key'
+  apiKey: 'new-secure-key',
+  timeout: 5000
 };

Response Example: ``` 🔒 Secure Diff Visualization

🔴 Security Level: High Security - Secret Gist + Password (15min auto-delete) 📋 Preview Link: https://htmlpreview.github.io/?... 🔑 Access Code: a7x9k2 ⏰ Auto-delete: 15 minutes ```

🔄 Fallback Functionality

When GitHub Token is unavailable, the system falls back to local files:

HTML saved as temporary file
Automatic browser opening
Security-based file management

For detailed setup and integration guides:

🇺🇸 English: CLAUDE_CODE_INTEGRATION.md
🇯🇵 日本語: CLAUDE_CODE_INTEGRATION_JP.md

🤝 Supported Clients

Claude Desktop (Primary)
Claude Code (CLI)
VS Code + MCP Extension
Cline and other MCP clients

📄 License

MIT License - see LICENSE file for details.

Dependencies

| Library | License | Purpose | |---------|---------|---------| | diff2html | MIT | HTML diff generation | | playwright-core | Apache 2.0 | Browser automation | | @modelcontextprotocol/sdk | MIT | MCP integration |

---

Made with ❤️ for the Claude Desktop community

unified-diff-mcp