MCPMender

MCPMender · 协议修匠

[](https://github.com/beyond5525/MCPMender/actions/workflows/release-builds.yml) [](https://github.com/beyond5525/MCPMender/releases) [](LICENSE) [](#desktop-installation)

MCPMender（协议修匠）是一款在本地运行的 MCP 配置诊断与安全修复工具， 同时提供 Desktop 图形界面和 mcpmender 命令行。

It helps people find out why an MCP server is not visible, will not start, or cannot complete an MCP handshake in Codex, Claude Desktop, Cursor, VS Code, VSCodium, Gemini CLI, and OpenCode.

Download MCPMender 0.3.0-beta.5 · 下载公开测试版 · パブリックベータをダウンロード →

Windows x64 · macOS Apple Silicon / Intel · Linux x64 · Command line

> Release status: 0.3.0-beta.5. This is a public beta, not a stable v1.0 > release. Keep a copy of important configuration and review every repair > preview before applying it.

MCPMender in 30 seconds

| | | |---|---| | The problem | An MCP server is missing, will not start, or fails its handshake—and the cause is unclear. | | Start safely | Run a read-only scan in the Desktop app or with mcpmender scan; configured tools are not launched during this scan. | | Go deeper only when needed | Preview an opt-in live connection test, or review an eligible low-risk repair before applying it. | | Stay in control | MCPMender runs locally, redacts common secrets in reports, backs up changed files, and records rollback information. |

Choose your path: Download the Desktop app · [Use the command line](#command-line-installation) · [Read the offline handbook](docs/MCPMender-Handbook.html) · Report a problem

Product tour · 产品介绍 · 製品紹介

[English](#english) · [简体中文](#简体中文) · [日本語](#日本語)

English

MCPMender finds MCP configuration problems in Codex, Claude Desktop, Cursor, VS Code, VSCodium, Gemini CLI, and OpenCode. Start with a read-only scan, optionally run a real connection check, preview eligible low-risk repairs, and use automatic backups and rollback when a change is applied. Everything runs locally, and reports redact common secret values.

| Diagnostics and safe repair | Trilingual offline handbook | |---|---| | | |

简体中文

协议修匠可以检查 Codex、Claude Desktop、Cursor、VS Code、VSCodium、Gemini CLI 和 OpenCode 的 MCP 配置问题。先进行完全只读的普通检测，需要时再执行真实连接 检查；符合安全条件的问题可以预览后一键修复，并自动备份、支持回滚。所有处理 都在本地完成，导出的报告会隐藏常见密钥和敏感值。

| 本地检测与安全修复 | 中文离线教程与帮助 | |---|---| | | |

日本語

MCPMender は Codex、Claude Desktop、Cursor、VS Code、VSCodium、Gemini CLI、 OpenCode の MCP 設定を検査します。最初は読み取り専用で診断し、必要な場合 だけ実際の接続確認を実行できます。安全な修復候補は変更内容を確認してから 適用でき、自動バックアップとロールバックにも対応します。処理はローカルで 完結し、レポートでは一般的な秘密情報を匿名化します。

| ローカル診断と安全な修復 | 日本語オフラインチュートリアル | |---|---| | | |

What it does

• Discovers supported MCP configuration files on Windows, macOS, and Linux.
• Checks JSON/JSONC/TOML syntax, commands, environment references, and URLs.
• Separates safe static scanning from opt-in live connection testing.
• Performs real MCP initialize handshakes over stdio or Streamable HTTP.
• Shows tool-list availability, timeouts, authentication failures, and process

cleanup results.

• Previews deterministic low-risk repairs, backs up the original file, verifies

that it has not changed, and supports rollback records.

• Exports machine-readable reports with common credentials and secret values

redacted.

• Provides English, Simplified Chinese, and Japanese in the app, CLI, and

bundled offline handbook.

MCPMender does not provide MCP servers, recover provider tokens, or guarantee that a discovered third-party server is trustworthy.

Scan or deep check?

| Operation | Runs configured MCP code? | Contacts remote MCP endpoints? | Writes configuration? | Best used for | |---|---:|---:|---:|---| | Scan / 普通扫描 | No | No | No | Finding malformed files, missing commands, missing environment references, and invalid URLs safely | | Probe / 深度检测 | Yes, after confirmation | Yes, after confirmation | No | Proving that a server starts or responds to a real MCP handshake | | Safe repair / 安全修复 | No | No | Only after confirmation | Applying an explicitly eligible repair after backup and change detection |

Always review mcpmender probe before running mcpmender probe --run. Configured commands are third-party code, and commands such as npx may download packages.

Desktop installation

Download the artifact for your operating system from the project Releases page. The exact artifact names are recorded in the release notes and checksum file.

Windows

1. Extract the release archive.
2. Open Windows\MCPMender\MCPMender.exe; installation is not required.
3. If Windows displays a publisher or SmartScreen warning, verify the published

SHA-256 checksum before deciding whether to run it.

Beta Windows builds may use a self-signed certificate. A self-signed signature can help detect modification, but it is not trusted automatically by Windows, Microsoft Defender SmartScreen, or other computers. It is not equivalent to a commercially issued code-signing certificate.

Windows ZIPs retained as GitHub Actions workflow artifacts are intentionally unsigned and include UNSIGNED-WINDOWS-BUILD.txt. Only a separately reviewed community build that includes the public certificate and matching thumbprint may be described as self-signed.

macOS

1. Choose the Apple Silicon package for M-series Macs or the Intel package for

Intel Macs.

1. Open the DMG and move MCPMender to Applications, or extract the ZIP.
2. If macOS blocks the first launch, inspect the app in **System Settings →

Privacy & Security** and use the system-provided approval flow only if the checksum matches the release.

Beta macOS builds may use ad-hoc signing and may not be notarized. Ad-hoc signing does not establish developer identity and is not trusted by Gatekeeper. Users should expect an operating-system warning.

Linux

For an AppImage:

chmod +x MCPMender*.AppImage
./MCPMender*.AppImage

If the AppImage cannot start because FUSE is unavailable, use its built-in extract-and-run fallback:

APPIMAGE_EXTRACT_AND_RUN=1 ./MCPMender*.AppImage

This only changes how the AppImage is launched. It does not repair MCP configuration, and it does not require sudo or root access.

For a tar.gz package:

tar -xzf MCPMender*.tar.gz
cd MCPMender*/
./mcpmender

Linux distributions differ in their available desktop libraries. If the app does not start, run it from a terminal and include the error output in a bug report after removing private paths and credentials.

Command-line installation

The release tarball requires Node.js 20.3 or newer. Download CLI/mcpmender-0.3.0-beta.5.tgz from the release archive, then run:

npm install --global ./mcpmender-0.3.0-beta.5.tgz
mcpmender --version
mcpmender --help

The npm registry package is not published yet. After an official npm beta is announced and npm view mcpmender dist-tags shows a beta tag, the equivalent registry command will be:

npm install --global mcpmender@beta

Common commands:

mcpmender scan
mcpmender scan --json
mcpmender scan --lang zh-CN
mcpmender probe
mcpmender probe --run
mcpmender probe --run --server server-name
mcpmender repair
mcpmender repair --apply-safe

--lang en, --lang zh-CN, and --lang ja are supported.

CLI exit codes are stable for automation:

| Exit code | Meaning | | ---: | --- | | 0 | Command completed and no blocking scan/probe failure was found | | 1 | Invalid command/options, unmatched server filter, or unexpected runtime failure | | 2 | Scan found errors, or a live probe failed/required authentication | | 3 | At least one requested safe repair was skipped or failed |

The Desktop backup-history panel can restore a recorded repair only when the current configuration still matches the repaired version. This prevents rollback from silently overwriting later user edits.

Upgrade and uninstall

MCPMender has no background service. Before upgrading, close the app and keep a copy of the adjacent data directory because it contains preferences, logs, and repair backups. Extract the new release to a new folder, start it once, and only then remove the old program files. Do not discard repair backups until the new version has successfully scanned the configurations you care about.

To uninstall the portable Desktop, close MCPMender and delete its program folder. Delete the adjacent data directory only if you also want to remove preferences, logs, and rollback backups. The CLI can be removed with npm uninstall --global mcpmender; uninstalling either interface does not delete MCP configuration files owned by Codex, Claude, Cursor, VS Code, VSCodium, Gemini CLI, or OpenCode. If the program folder was not writable, MCPMender uses a fallback data location and shows its exact path in the interface. Note that path before closing the app, then delete it manually after MCPMender exits if you want a complete data removal. If the program was already deleted, extract and run the same release once more to display the fallback path.

Privacy and security

• No account, telemetry, analytics, or MCPMender cloud service is required.
• Scans, reports, backups, and settings stay on the local computer unless the

user deliberately shares them.

• A static scan does not start configured commands or contact MCP endpoints.
• A deep check necessarily starts the selected local command or contacts the

selected remote endpoint.

• Report redaction reduces accidental disclosure but is not a guarantee; review

an exported report before sharing it.

• MCP configuration can contain executable commands and secrets. Do not publish

raw configuration files in Issues.

See [PRIVACY.md](PRIVACY.md) and [SECURITY.md](SECURITY.md).

Development

The repository uses pnpm workspaces:

powershell.exe -NoProfile -ExecutionPolicy Bypass -File .\tools\dev.ps1 install
powershell.exe -NoProfile -ExecutionPolicy Bypass -File .\tools\dev.ps1 test
powershell.exe -NoProfile -ExecutionPolicy Bypass -File .\tools\dev.ps1 build
powershell.exe -NoProfile -ExecutionPolicy Bypass -File .\tools\dev.ps1 desktop

Run the CLI from the checkout:

powershell.exe -NoProfile -ExecutionPolicy Bypass -File .\tools\dev.ps1 cli -- scan --lang zh-CN
powershell.exe -NoProfile -ExecutionPolicy Bypass -File .\tools\dev.ps1 cli -- probe
powershell.exe -NoProfile -ExecutionPolicy Bypass -File .\tools\dev.ps1 cli -- probe --run
powershell.exe -NoProfile -ExecutionPolicy Bypass -File .\tools\dev.ps1 cli -- repair

The offline three-language handbook is [docs/MCPMender-Handbook.html](docs/MCPMender-Handbook.html). See [CONTRIBUTING.md](CONTRIBUTING.md) before submitting a change.

Release confidence

Release artifacts should be built and smoke-tested on their native operating systems. A passing automated build proves repeatability, but does not replace manual checks of operating-system warnings, fonts, permissions, configuration discovery, deep-check cleanup, report export, and rollback.

The release owner uses [RELEASECHECKLIST.md](RELEASECHECKLIST.md) to record what was actually verified. Missing native or manual checks must be disclosed in the release notes instead of being described as passed.

License

Apache-2.0. See [LICENSE](LICENSE). Direct dependency sources and licenses are listed in [THIRDPARTYNOTICES.md](THIRDPARTYNOTICES.md).

Source & license

This open-source MCP server is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: beyond5525
• Source: beyond5525/MCPMender
• License: Apache-2.0

Install and usage instructions live in the source repository linked above.