Préparez, inspectez et appliquez des bundles de modifications Git portables sur des dépôts hors ligne ou isolés (air-gapped).
Aussi connu sous mayank1307/gitferry
- Étoiles
- 0
- Outils
- —
- Téléchargements, 30 jours
- —
- Dernière version
- 0.4.2
- Dernier commit
- 4 nov. 2026
- Licence
- MIT
Qu'est-ce que GitFerry MCP ?
Préparez, inspectez et appliquez des bundles de modifications Git portables sur des dépôts hors ligne ou isolés (air-gapped).
Résumé généré à partir du README du projet
À propos du MCP server GitFerry
GitFerry offre une solution pour déplacer des modifications Git entre des machines incapables de se connecter à un dépôt distant ou à un réseau partagé. Il est conçu pour les développeurs travaillant dans des environnements isolés (air-gapped), chez des clients, ou dans des scénarios hors ligne où les données doivent être transférées via USB, e-mail ou même par codes QR. L'outil regroupe les commits non poussés, les modifications indexées ou non, ainsi que les fichiers non suivis dans un fichier portable unique qui préserve l'état exact du worktree.
Ce MCP server s'exécute localement via stdio, ce qui signifie qu'il interagit avec les dépôts sur la même machine que le client. Une fois installé, il ne nécessite aucune clé API, aucun compte, ni aucun accès Internet. Les utilisateurs peuvent l'intégrer à des clients tels que Claude Code ou Codex pour automatiser la création et l'application de bundles de modifications. Le serveur propose des outils spécifiques pour pack_changes, inspect_bundle et apply_bundle, garantissant que chaque transfert est validé par des sommes de contrôle sha256 et des vérifications d'empreinte du dépôt avant toute modification de fichier.
Ce que vous pouvez faire avec
- 1Transférer du travail vers des machines isoléesCréez un bundle contenant toutes les modifications non validées et les fichiers non suivis pour les déplacer vers un dépôt hors ligne via USB.
- 2Transférer des données via des codes QR visuelsEnvoyez de petits patchs entre deux machines en affichant une séquence de codes QR sur un écran et en les lisant avec une webcam sur l'autre.
- 3Synchroniser des instantanés de dépôts completsCapturez un instantané complet de chaque fichier suivi pour initialiser une nouvelle machine avec l'état d'un dépôt existant.
Extrait du README du projet. Chaque cas d'utilisation est vérifié par rapport à une citation du document.
Comment installer GitFerry MCP
Formats vérifiés le 10 nov. 2026Ajouter à CursorAjouter à GooseInstaller GitFerry MCP dans Claude Code
$ claude mcp add gitferry -- npx -y gitferryInstaller GitFerry MCP dans Cursor
~/.cursor/mcp.json
{
"mcpServers": {
"gitferry": {
"command": "npx",
"args": [
"-y",
"gitferry"
]
}
}
}Installer GitFerry MCP dans VS Code
.vscode/mcp.json
{
"servers": {
"gitferry": {
"type": "stdio",
"command": "npx",
"args": [
"-y",
"gitferry"
]
}
}
}Installer GitFerry MCP dans VS Code CLI
$ code --add-mcp '{"name":"gitferry","type":"stdio","command":"npx","args":["-y","gitferry"]}'Installer GitFerry MCP dans Claude Desktop
claude_desktop_config.json
{
"mcpServers": {
"gitferry": {
"command": "npx",
"args": [
"-y",
"gitferry"
]
}
}
}Installer GitFerry MCP dans Codex
$ codex mcp add gitferry -- npx -y gitferryInstaller GitFerry MCP dans Codex config.toml
~/.codex/config.toml
[mcp_servers.gitferry] command = "npx" args = ["-y", "gitferry"]
Installer GitFerry MCP dans Gemini CLI
$ gemini mcp add -s user gitferry npx -- -y gitferryInstaller GitFerry MCP dans Gemini settings.json
~/.gemini/settings.json
{
"mcpServers": {
"gitferry": {
"command": "npx",
"args": [
"-y",
"gitferry"
]
}
}
}Vérifications automatisées
Exécuté le 14 nov. 2026Rapport complet →A passé nos vérifications automatisées. Il ne s'agit pas d'un audit de sécurité : lisez le code et donnez au serveur l'accès le plus restreint dont il a besoin. Fonctionnement des vérifications
- Dépôt source lié et accessiblemayank1307/gitferry is public and reachablegithub.com/mayank1307/gitferry ↗Réussi
- Le nom du package correspond au dépôt sourcegitferry names mayank1307/gitferry as sourcenpmjs.com/package/gitferry ↗Réussi
- Provenance du build (attestation Sigstore)Sigstore attestation for gitferrynpmjs.com/package/gitferry/v/0.4.2#provenance ↗Réussi
- Licence open source (OSI)MITspdx.org/licenses/MIT.html ↗Réussi
- Commit ou version publiée au cours de l'année écouléeLast commit or release 2026-11-04github.com/mayank1307/gitferry ↗Réussi
- OpenSSF ScorecardNon vérifié
- Nom du package non proche d'un package populaireNo popular package one edit away from gitferryRéussi
- Aucun avis critique dans le package ou ses dépendances131 resolved dependencies checked; no critical advisoryosv.dev ↗Réussi
- Aucune instruction cachée destinée au modèle0 tool descriptions and the README read; no override phrases, credential paths or hidden charactersRéussi
- Les outils destructifs sont étiquetésNon vérifié
- Le point de terminaison distant répond à la poignée de main MCPNon vérifié
README
Voir sur GitHubgitferry
v0.4.2 is released. npm package · v0.4.2 release and downloads · MCP Registry
Portable git-change bundles for air-gapped repos. Pack your unpushed commits, staged/unstaged changes, and untracked files into a single shareable file on one machine — carry it across the air gap (USB, secure file transfer, email, or QR codes across a webcam) — validate and apply it to the same repo on another machine. No shared remote, no network, no sync required.
machine A (has your changes) machine B (same repo, no sync)
┌─────────────────────────┐ ┌─────────────────────────┐
│ $ gitferry pack │ ──────▶ │ $ gitferry apply │
│ → repo-main-a1b2c3d │ USB / │ ✓ checksums verified │
│ .gitferry │ scp / │ ✓ same repo confirmed │
│ │ email │ ✓ 2 commits replayed │
│ commits + worktree │ │ ✓ staged/unstaged │
│ + untracked, checksummed│ │ state restored │
└─────────────────────────┘ └─────────────────────────┘
See SCENARIOS.md for every situation this is built for — air-gapped environments, client-site work, WIP handoffs, offline review, and more. See INSTALL.md for offline installation on other devices.
Quick MCP install (Claude Code): claude mcp add --transport stdio gitferry -- npx --yes --package=gitferry@0.4.2 gitferry-mcp, then restart your client and confirm the pack_changes, inspect_bundle, and apply_bundle tools appear. Codex, VS Code, JSON config, and offline setup are in MCP server below.
Why not just git format-patch / git bundle?
You can — gitferry uses them under the hood. What raw git doesn't give you:
- Untracked files travel too (respecting
.gitignore) —git diffnever sees them - Staged vs unstaged state is preserved — your index looks the same on the other side
- Validation before anything touches the repo: sha256 checksums of every file, same-repository fingerprint check (root commits), base-commit check, clean-tree check
- One command each way instead of a multi-step
format-patch/diff/am/applychoreography - Binary-safe (
--binarypatches for tracked files, verbatim bytes for untracked) - Plain-git fallback: the bundle is a zip of standard git patches — pack with
--portableand a machine with only git + unzip applies it by hand (instructions are inside every bundle; the compact default needs node's one-liner to unwrap first)
Install
Requires Node.js 22 or newer and Git 2.32 or newer. Install the published CLI and MCP server from npm:
npm install -g gitferry@0.4.2
gitferry --version
For MCP-only use, skip the global install and use the pinned npx configuration in MCP server.
Installation and MCP registration are separate steps. Installing the npm package makes gitferry and gitferry-mcp available in your terminal. Registering the server tells Codex, Claude Code, or another MCP client how to launch it. With npx, the client downloads the pinned package on first launch, so a global install is optional. Reading this README or installing the package alone does not register the server.
Closed environments (no npm)
Download gitferry.cjs, gitferry-mcp.cjs, and SHA256SUMS from the public v0.4.2 release. These standalone files include their JavaScript dependencies; transfer them to the offline machine with Node and Git. See INSTALL.md for checksum verification and setup.
To build the same standalone executables from a source checkout:
npm run bundle # → dist/gitferry.cjs + dist/gitferry-mcp.cjs
node dist/gitferry.cjs pack # runs without any install or node_modules
Usage
On the machine with changes
gitferry pack # asks what should travel (Enter = uncommitted); base = merge-base with upstream
gitferry pack --only staged # skip the question: all | uncommitted | staged | unstaged | committed | repo
gitferry pack --only repo # whole-repo snapshot: every tracked file as-is — seed/sync another machine
gitferry pack --base origin/main # explicit base
gitferry pack -o changes.gitferry --no-untracked
The interactive picker only appears in a terminal; in scripts (no TTY) pack takes everything unless --only or --no-* flags say otherwise. Selections mean: all = commits + staged + unstaged + untracked · uncommitted = everything except commits · staged = index edits only · unstaged = worktree edits + untracked · committed = unpushed commits only · repo = a snapshot of every tracked file as it is on disk (no history) — apply seeds a bare directory or syncs an existing checkout, skipping identical files and touching drifted ones only with --force.
On the receiving machine
gitferry inspect changes.gitferry # verify + preview, touches nothing
gitferry apply changes.gitferry --dry-run
gitferry apply changes.gitferry
No transfer channel at all? Beam it over QR
When even USB is off the table, the screen itself is the channel: one machine plays the bundle as a looping sequence of QR codes, the other watches with any webcam.
# machine A (sender)
gitferry show changes.gitferry # QR loop right in the terminal
gitferry show changes.gitferry --browser # bigger + denser, in a local browser page
gitferry show changes.gitferry --color # experimental: 3x density, 3 chunks per image in R/G/B
# machine B (receiver) — point its webcam at A's screen
gitferry read # opens a local camera page, reassembles the bundle
gitferry apply changes.gitferry
Every QR frame carries its chunk number / total plus a transfer id, so the receiver knows exactly which pieces it still needs — it shows the missing numbers live and keeps collecting as the loop repeats (order doesn't matter; missed frames come around again). The file is only written once every numbered chunk arrived and the whole-file sha256 matches, so a completed read is proof nothing was skipped or corrupted. Both pages live on 127.0.0.1; no network between the machines is used or needed.
Point the sender's webcam back at the receiver and the loop gets smart. The read page displays a small progress QR of its own (tiny payload, high error correction, so it scans easily). If the show --browser machine also has a camera watching the receiver's screen, then after each loop the sender re-shows only the chunks that are still missing, dropping from the first-loop rate (default 4 fps) to a slower retry rate (default 1 fps, --retry-fps) so the stragglers are easy to catch — and stops automatically once the receiver's code says complete. No camera on the sender's side? Everything simply loops at full speed like before.
Throughput is roughly chunk × fps: defaults give ~0.3 KB/s in the terminal, ~0.6 KB/s in the browser, ~1.8 KB/s with --color — meant for patch-sized bundles, not megabyte piles (pack --no-untracked helps keep them small). The default is deliberately a coarse, easy-scan code (150 bytes ≈ QR version 8, 49×49 modules): webcams reading another screen fail on fine modules long before they fail on frame count. Raise --chunk (up to 2900) if your camera and screens are good.
Applying
Apply order: commits (git am -3, full author/date/message preserved) → staged patch (index + worktree) → unstaged patch (worktree only) → untracked files (never overwrites existing files unless --force).
On conflicts you get standard git conflict markers and clear instructions (git am --continue / --abort, .rej files as last resort) — application is not transactional, so review the error and recovery instructions before continuing.
Flags
| Flag | Command | Effect |
|---|---|---|
--base <ref> |
pack | commit the bundle applies onto |
--only <what> |
pack | all / uncommitted / staged / unstaged / committed / repo — non-interactive selection |
--no-commits / --no-worktree / --no-untracked |
pack | trim what's captured (combinable with --only) |
--portable |
pack | plain-zip bundle (~30% bigger) for targets with only git + unzip |
--dry-run |
apply | validate + show the plan, change nothing |
--force |
apply | override same-repo, clean-tree, and overwrite guards |
-C <dir> |
pack/apply | run against another directory |
--chunk <bytes> / --fps <n> |
show | QR payload size (default 150 ≈ version-8 code; raise for speed, lower for even easier scanning) and first-loop display speed |
--retry-fps <n> |
show | slower rate for re-loops of missing chunks once the receiver's progress QR is seen (default 1) |
--browser / --color |
show | browser-page display; experimental 3× density via R/G/B channels |
--no-open / --port <n> |
show/read | don't auto-open the local page / pin its port |
-o <file> / --force |
read | output path / overwrite an existing file |
MCP server
GitFerry runs locally over stdio. Your MCP client starts the process, and it works with repositories on that same machine. No GitFerry account, API key, hosted service, or source upload is required. URL-only MCP clients need a separate bridge and cannot connect directly to this local server.
Register with the CLI for your client (requires Codex CLI or Claude Code, respectively):
# Codex
codex mcp add gitferry -- npx --yes --package=gitferry@0.4.2 gitferry-mcp
codex mcp get gitferry
# Claude Code
claude mcp add --transport stdio gitferry -- npx --yes --package=gitferry@0.4.2 gitferry-mcp
claude mcp get gitferry
Choose your client's registration command, reconnect or start a new session, and verify that pack_changes, inspect_bundle, and apply_bundle are available. mcp get confirms the saved configuration; tool discovery in the connected client confirms the server is working. See Codex setup for the TOML alternative and agent-assisted installation to delegate setup.
Use this configuration for the published 0.4.2 package in clients that accept mcpServers JSON. The explicit executable matters because this package supplies both a CLI and an MCP server:
{
"mcpServers": {
"gitferry": {
"command": "npx",
"args": ["--yes", "--package=gitferry@0.4.2", "gitferry-mcp"]
}
}
}
For a source checkout, build with npm ci && npm run bundle and use:
{
"mcpServers": {
"gitferry": {
"command": "node",
"args": ["/absolute/path/to/gitferry/dist/gitferry-mcp.cjs"]
}
}
}
If you installed the package globally, the server command is gitferry-mcp. For a downloaded offline bundle, point node directly at /absolute/path/to/gitferry-mcp.cjs. See client setup for Codex, Claude Code, and VS Code examples and Windows launch instructions.
| Tool | Action | Key arguments |
|---|---|---|
pack_changes |
Writes a portable bundle from local changes | cwd, optional output, base, only, portable and include flags |
inspect_bundle |
Reads and validates a bundle without changing a repository | bundlePath |
apply_bundle |
Previews or applies a bundle to a local target | cwd, bundlePath, dryRun, force, includeUntracked |
Use absolute paths. Start with: “Pack the uncommitted changes in /absolute/path/to/repo into /absolute/path/to/transfer.gitferry.” On the receiving machine: “Inspect this bundle, then dry-run it against /absolute/path/to/repo and show the plan before applying.”
only accepts all, uncommitted, staged, unstaged, committed, or repo. Snapshot mode (repo) carries current tracked-file contents rather than history; it can seed an empty directory. The default without a selection includes all change categories, matching non-interactive CLI use. Tool annotations describe side effects to the client; they do not enforce approvals or restrict filesystem access.
See INSTALL.md for setup and offline transfer, DEMO.md for a two-repository walkthrough, and PUBLISHING.md for maintainer release steps. Published registry identity: io.github.mayank1307/gitferry.
Agent-assisted installation
Paste this into Codex or Claude Code with terminal and configuration access:
Set up GitFerry v0.4.2 as a local stdio MCP server in this client using https://github.com/mayank1307/gitferry/blob/main/INSTALL.md. Check Node.js 22+ and Git 2.32+. Check for an existing GitFerry registration, preserve other servers, and register the pinned npx command for this client. A global npm install is optional. Verify the saved configuration, then verify that pack_changes, inspect_bundle, and apply_bundle are available. If a restart or new session is needed, tell me what to do and verify tool discovery afterward.
The agent can perform setup when asked and given the required access. Package download happens automatically through npx after registration; client approvals and reconnection follow the client's normal behavior.
Bundle format
A .gitferry file is a zip with this layout — by default brotli-wrapped (GFBR magic + brotli stream of a stored zip, ~30% smaller than a deflate zip; pack --portable writes a plain zip instead, and inspect/apply auto-detect both):
manifest.json # versioned manifest: repo fingerprint, base/head shas,
# content listing, sha256 of every entry
commits/00NN-*.patch # git format-patch output (mbox — author, date, message)
worktree/staged.patch # git diff --binary --cached
worktree/unstaged.patch # git diff --binary
untracked/<paths> # verbatim file bytes
README.txt # human instructions for manual apply with plain git
Everything inside is standard-git-consumable by design; gitferry adds integrity checking and one-command UX, never a proprietary encoding. For a target with only git + unzip, pack with --portable; the compact default can still be unwrapped by any machine with node (the one-liner is in the bundle's own README.txt).
Notes & limitations
- Merge commits in the packed range are flattened by
format-patch— pack warns; prefer linear branches or pick a different--base - Replayed commits get new shas (same content/author, new committer) — normal for
git am - Change bundles require shared repository history (validated via root-commit fingerprint); snapshot bundles can also seed an empty directory.
- Requires git ≥ 2.32 on the applying machine
Safety and trust
Bundles contain source code, commit messages, and potentially untracked secrets. Review the selection and destination before sharing. .gitignore excludes ignored untracked files; it does not remove secrets already tracked in Git. Checksums detect corruption, not the identity or trustworthiness of the sender. Only apply bundles from sources you trust.
The server has the filesystem privileges of the process that starts it. Configure it only in trusted clients and run it as your normal user. force bypasses repository, dirty-tree, and overwrite guards. See SECURITY.md for enforced limits, symlink behavior, and concurrency boundaries.
Development
See repository architecture for the source layout and MCP deployment for local, npm, and Docker setup. Copyable client configurations live in examples/mcp.
npm ci
npm run build # tsc → dist/
npm test # vitest: round-trip e2e on real temp repos + guard tests
npm run bundle # fresh single-file CLI + MCP server
npm run release:check # versions, build, tests, and isolated package smoke test
Questions sur GitFerry MCP
Comment ajouter GitFerry MCP à Claude Code ?
Exécutez claude mcp add gitferry -- npx -y gitferry dans votre terminal. Ajoutez --scope user pour le rendre disponible dans tous les projets.
Comment ajouter GitFerry MCP à Cursor ?
Ouvrez ~/.cursor/mcp.json et ajoutez le serveur sous mcpServers, avec la configuration Cursor indiquée dans la section d'installation ci-dessus.
Puis-je transférer des modifications sans clé USB ni réseau ?
Oui, vous pouvez utiliser la commande 'show' pour afficher le bundle sous forme de séquence de codes QR, lisibles par la webcam d'une autre machine.
GitFerry nécessite-t-il une connexion Internet ou un compte ?
Non, il s'exécute localement via stdio et ne nécessite ni compte, ni clé API, ni service hébergé.