Skip to main content
Glama
beyondcompare-mcp

beyondcompare-mcp

Beyond Compare MCP Server

License MCP

Model Context Protocol (MCP) server for Beyond Compare, the powerful file and folder comparison tool for Windows. Enables file comparison, folder diffing, 3-way merging, folder sync, and scripted automation through MCP.

Features

  • File Comparison: Compare two files with binary, text, hex, or rules-based analysis

  • Folder Comparison: Diff entire directory trees with optional file filters

  • 3-Way Merge: Merge files with base/left/right and auto-merge support

  • Folder Sync: Synchronize directory contents between locations

  • Script Automation: Run Beyond Compare scripts for batch operations

  • Rich Exit Codes: Structured results (same, different, similar, conflicts)

Related MCP server: semamerge

Prerequisites

Windows Only - Beyond Compare 5 must be installed:

  1. Install via winget:

    winget install ScooterSoftware.BeyondCompare.5
  2. Or download: https://www.scootersoftware.com/download

  3. Verify BComp.com is available at the default path or set BCOMP_PATH

Installation

From Source

git clone https://github.com/danielsimonjr/beyondcompare-mcp.git
cd beyondcompare-mcp
bun install
bun run build

The server is written in TypeScript and builds to dist/. Bun is the development toolchain; Node is the runtime the server ships on.

Configuration

Claude Desktop

Add to your claude_desktop_config.json:

{
  "mcpServers": {
    "beyondcompare-mcp": {
      "command": "node",
      "args": ["C:\\mcp-servers\\beyondcompare-mcp\\dist\\index.js"]
    }
  }
}

Claude Code

Add to your ~/.claude/.mcp.json:

{
  "mcpServers": {
    "beyondcompare-mcp": {
      "command": "node",
      "args": ["C:\\mcp-servers\\beyondcompare-mcp\\dist\\index.js"]
    }
  }
}

Custom BComp.com Path

If Beyond Compare is installed in a non-default location, set the BCOMP_PATH environment variable:

{
  "mcpServers": {
    "beyondcompare-mcp": {
      "command": "node",
      "args": ["C:\\mcp-servers\\beyondcompare-mcp\\dist\\index.js"],
      "env": {
        "BCOMP_PATH": "D:\\Programs\\Beyond Compare 5\\BComp.com"
      }
    }
  }
}

VS Code

Add to .vscode/mcp.json:

{
  "servers": {
    "beyondcompare-mcp": {
      "command": "node",
      "args": ["C:\\mcp-servers\\beyondcompare-mcp\\dist\\index.js"]
    }
  }
}

Available Tools

1. compare_files

Compare two files using Beyond Compare. Returns whether files are identical, similar, or different.

Parameters:

  • left (required): Path to the left (source) file

  • right (required): Path to the right (target) file

  • fileViewType (optional): Comparison type — text, hex, table, mp3, picture, registry, version

  • silent (optional): Quick comparison without GUI (default: true)

  • readOnly (optional): Open files as read-only (default: false)

Example:

{
  "left": "C:\\project\\old\\config.json",
  "right": "C:\\project\\new\\config.json",
  "silent": true
}

Returns: SAME, SIMILAR, DIFFERENT, or ERROR with Beyond Compare exit code details.

2. compare_folders

Compare two folders and report differences in contents.

Parameters:

  • left (required): Path to the left (source) folder

  • right (required): Path to the right (target) folder

  • filters (optional): File filter pattern (e.g., *.js;*.ts or -*.log)

  • silent (optional): Quick comparison without GUI (default: true)

Example:

{
  "left": "C:\\project\\v1\\src",
  "right": "C:\\project\\v2\\src",
  "filters": "*.ts;*.tsx",
  "silent": true
}

3. merge_files

Perform a 3-way merge with base, left, and right files.

Parameters:

  • left (required): Path to the left file

  • right (required): Path to the right file

  • center (required): Path to the center (base/ancestor) file

  • output (required): Path for the merged output file

  • automerge (optional): Auto-merge non-conflicting changes (default: false)

  • reviewConflicts (optional): Open GUI if automerge finds conflicts (default: false)

  • favorLeft (optional): Favor left side for conflicts (default: false)

  • favorRight (optional): Favor right side for conflicts (default: false)

Example:

{
  "left": "C:\\merge\\mine.txt",
  "right": "C:\\merge\\theirs.txt",
  "center": "C:\\merge\\base.txt",
  "output": "C:\\merge\\result.txt",
  "automerge": true,
  "reviewConflicts": true
}

Returns: SUCCESS, CONFLICTS, or ERROR.

4. sync_folders

Open a Folder Sync session to synchronize two directories.

Parameters:

  • left (required): Path to the left (source) folder

  • right (required): Path to the right (target) folder

  • filters (optional): File filter pattern (e.g., -node_modules;-.git)

Example:

{
  "left": "C:\\source\\project",
  "right": "D:\\backup\\project",
  "filters": "-node_modules;-.git;-dist"
}

5. run_script

Run a Beyond Compare script file for automated batch operations.

Parameters:

  • scriptPath (required): Path to the Beyond Compare script file

  • silent (optional): Run without showing a window (default: true)

  • closeWhenDone (optional): Close script window when finished (default: true)

Example:

{
  "scriptPath": "C:\\scripts\\nightly-backup-compare.txt"
}

Sample script file (nightly-backup-compare.txt):

folder-report layout:side-by-side &
  options:display-mismatches &
  output-to:"C:\reports\diff-report.html" output-options:html-color &
  "C:\source" "C:\backup"

Exit Codes

Beyond Compare returns meaningful exit codes that the MCP server translates:

Code

Meaning

0

Success

1

Binary same

2

Rules-based same

11

Binary differences

12

Similar

13

Rules-based differences

14

Conflicts detected

100

Error

101

Conflicts detected, merge output not saved

Usage Examples

Example 1: Check if Two Config Files Match

Tell Claude:

Compare my dev and prod config files to see if they're in sync

Example 2: Diff Two Project Versions

Tell Claude:

Compare the src folders between v1 and v2 of my project, only looking at TypeScript files

Example 3: Auto-Merge a Git Conflict

Tell Claude:

Merge these three versions of the file — base, mine, and theirs — and auto-resolve what you can

Example 4: Run a Backup Comparison Script

Tell Claude:

Run my nightly backup comparison script at C:\scripts\backup-check.txt

How It Works

  1. Beyond Compare CLI: BC exposes BComp.com (console) and BComp.exe (GUI) for command-line operations

  2. MCP Server: Wraps BComp.com and translates arguments into CLI calls

  3. Exit Code Parsing: Rich exit codes are mapped to human-readable verdicts (SAME, DIFFERENT, SIMILAR, CONFLICTS)

  4. Timeout Management: Operations have appropriate timeouts (60s files, 120s folders, 300s merge/sync, 600s scripts)

Troubleshooting

Beyond Compare Not Found

Error: Failed to execute BComp.com

Solutions:

  1. Verify Beyond Compare 5 is installed: winget list ScooterSoftware.BeyondCompare.5

  2. Check the default path: C:\Users\<username>\AppData\Local\Programs\Beyond Compare 5\BComp.com

  3. Set BCOMP_PATH environment variable in your MCP config

Timeout on Large Comparisons

Issue: Folder comparisons or syncs time out

Solution: For very large directory trees, use filters to narrow the scope, or use run_script with a Beyond Compare script that has more control over the operation.

License Required

Beyond Compare requires a license for full functionality. A 30-day trial is available. Without a license, some features may be limited.

Development

# Clone repository
git clone https://github.com/danielsimonjr/beyondcompare-mcp.git
cd beyondcompare-mcp

# Install dependencies (Bun >= 1.4.2)
bun install

# Type-check, test, build
bun run typecheck
bun run test
bun run build

# Run the built server the way a client does
node dist/index.js

# Confirm the built artifact speaks MCP
node scripts/smoke.mjs

Layout

Path

Holds

src/bcomp.ts

Locating and running BComp.com; exit-code meanings

src/report.ts

Parsing Beyond Compare XML folder reports

src/tools.ts

Tool schemas paired with their handlers

src/server.ts

buildServer() -- MCP wiring, no side effects

src/index.ts

Entry point: connect stdio and start

The tests import these modules directly. src/index.ts is the only file that starts anything, which is what keeps the rest testable.

Contributing

Contributions welcome! Please:

  1. Fork the repository

  2. Create a feature branch

  3. Make your changes

  4. Test thoroughly

  5. Submit a pull request

License

MIT License - see LICENSE file for details.

Acknowledgments


Made with care for the MCP community

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    Related MCP Connectors

    Related MCP Servers

    • F
      license
      Not graded
      quality
      Not graded
      maintenance
      Enables intelligent file and folder comparison with advanced text normalization, duplicate detection, and line-level diff analysis. Provides secure workspace-constrained file operations with CRC32-based exact matching and smart text comparison capabilities.
      -
    • A
      license
      A
      quality
      D
      maintenance
      MCP server that detects semantic (non-textual) merge conflicts between Git branches using AST-level analysis. Catches incompatible changes that Git merges cleanly — signature changes, removed exports, parameter changes, interface breaks, and cross-file dependency conflicts.
      4
      48 npm
      MIT
    • A
      license
      A
      quality
      B
      maintenance
      Provides safe, deterministic inspection, transformation, validation, and diffing of structured data (JSON, CSV, YAML, Parquet) via schema-aware MCP tools.
      4
      Apache 2.0