Unified Diff MCP Server

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

bash

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:

bash

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)

Code

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

Save diff locally

Code

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:
server.ts
```
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:

config.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):

config.json

{
  "command": "bun",
  "args": ["--watch", "/path/to/unified-diff-mcp/src/index.ts"]
}

Production mode:

config.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

server.ts

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:

Code

🔒 **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