mcp-sandboxed-git-gh-cli

An MCP server that runs git and gh CLI commands outside Claude Code's macOS sandbox, working around known sandbox bugs that break:

• Git SSH signing -- sandbox blocks SSH/raw TCP, preventing commit signing with SSH keys
• GitHub CLI (gh) TLS -- sandbox blocks com.apple.trustd.agent Mach IPC, causing Go binaries to fail with x509: OSStatus -26276
• Heredoc temp files -- sandbox blocks /tmp writes needed for multi-line commit messages

The server runs as a standalone binary that inherits the user's configured environment -- no shell, no profile scripts, no implicit state.

Configure in Claude Code

Register the server globally with claude mcp add, or add a .mcp.json at the project root to share it with collaborators.

The server progressively discloses tools based on what you configure. Only git and doctor are always available. The gh tool requires explicit authentication configuration.

Minimal: git only

No env vars needed. The MCP SDK passes HOME and PATH by default, which is enough for local git operations (status, log, diff, add, commit, branch, etc.).

claude mcp add -s user -t stdio mcp-sandboxed-git-gh-cli \
  /absolute/path/to/dist/mcp-sandboxed-git-gh-cli

git + SSH

Required for git push/pull over SSH and SSH commit signing. Forward the SSH agent socket so the server can reach your keys.

claude mcp add -s user -t stdio mcp-sandboxed-git-gh-cli \
  -e SSH_AUTH_SOCK='${SSH_AUTH_SOCK}' \
  /absolute/path/to/dist/mcp-sandboxed-git-gh-cli

git + gh (with account selection)

The gh tool is only registered when you explicitly configure authentication. This prevents the server from silently using the wrong account.

Recommended: select a specific gh account (works with SSO and multi-account setups):

claude mcp add -s user -t stdio mcp-sandboxed-git-gh-cli \
  -e SSH_AUTH_SOCK='${SSH_AUTH_SOCK}' \
  -e MCP_GH_USER=your-github-username \
  /absolute/path/to/dist/mcp-sandboxed-git-gh-cli

At startup the server runs gh auth token --user <value> to resolve the account's token from your local gh credential store. No global state is mutated -- the token is extracted and used for this server session only.

Alternative: use a personal access token directly:

claude mcp add -s user -t stdio mcp-sandboxed-git-gh-cli \
  -e SSH_AUTH_SOCK='${SSH_AUTH_SOCK}' \
  -e GH_TOKEN=ghp_... \
  /absolute/path/to/dist/mcp-sandboxed-git-gh-cli

Alternative: point to a gh config directory:

claude mcp add -s user -t stdio mcp-sandboxed-git-gh-cli \
  -e SSH_AUTH_SOCK='${SSH_AUTH_SOCK}' \
  -e GH_CONFIG_DIR='${HOME}/.config/gh' \
  /absolute/path/to/dist/mcp-sandboxed-git-gh-cli

claude mcp add writes to ~/.claude.json (user scope) or .claude.json in the project root (project scope).

Alternatively, add a .mcp.json at the project root -- useful for sharing the config with collaborators:

{
  "mcpServers": {
    "mcp-sandboxed-git-gh-cli": {
      "command": "/absolute/path/to/dist/mcp-sandboxed-git-gh-cli",
      "env": {
        "SSH_AUTH_SOCK": "${SSH_AUTH_SOCK}",
        "MCP_GH_USER": "your-github-username"
      }
    }
  }
}

Make the tools discoverable

Claude Code loads MCP tools lazily -- they don't appear until you search for them. To make sure agents reach for these tools instead of Bash, add the following to your project's CLAUDE.md or AGENTS.md:

## Git and gh run outside the sandbox

SSH signing and TLS break inside the macOS sandbox. This project has an MCP server that sidesteps that. Use these instead of Bash for all git/gh work:

- `mcp__mcp-sandboxed-git-gh-cli__git` -- git with working SSH signing
- `mcp__mcp-sandboxed-git-gh-cli__gh` -- gh with working TLS

Both are deferred tools. ToolSearch them before first use.

This works with any agent that reads CLAUDE.md or AGENTS.md -- symlink one to the other if you want to stay agent-agnostic.

gh authentication priority

When multiple auth variables are set, the server uses the first match:

1. MCP_GH_USER -- resolves token via gh auth token --user <value>
2. GH_TOKEN / GITHUB_TOKEN -- uses token directly
3. GH_CONFIG_DIR -- defers to the active account in that config directory

Environment variables reference

The MCP SDK passes HOME, LOGNAME, PATH, SHELL, TERM, and USER by default. Anything else must be explicitly forwarded via -e flags or the env block.

Only include variables that are set in your environment -- unset ${VAR} references cause warnings.

Tools

git

Always available. Run git subcommands allowed by the active security policy.

Some subcommands have restricted flags under the default policy. See Security policy for the full table.

gh

Available only when gh authentication is configured. Run gh subcommands allowed by the active security policy.

Some subcommands have restricted actions under the default policy. See Security policy for the full table.

doctor

Always available. Takes no arguments. Diagnoses the server environment and reports:

• Binary availability (git, gh, ssh, gpg)
• Git identity (user.name, user.email)
• SSH agent status
• gh authentication status and method
• Which tools are active and why
• Actionable recommendations for fixing issues

Run the doctor tool after registering the server to verify your configuration.

Prerequisites

• git installed and on PATH

Optional, depending on configuration:

• gh installed and authenticated (gh auth login) for the gh tool
• SSH agent running for SSH operations
• gpg installed for GPG commit signing

Install

bun install

Build

bun run build

Produces a standalone executable at dist/mcp-sandboxed-git-gh-cli (~66 MB). The binary is large because bun build --compile embeds the entire Bun runtime (JavaScriptCore engine, Node.js API compatibility, crypto, etc.). The actual application code is a few hundred KB -- the rest is the runtime. The tradeoff: no runtime dependencies needed on the target machine.

Run (development)

bun run start

Test

Smoke test (initialize handshake)

echo '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2024-11-05","capabilities":{},"clientInfo":{"name":"test","version":"0.1.0"}}}' \
  | ./dist/mcp-sandboxed-git-gh-cli

Run the doctor tool

printf '%s\n' \
  '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2024-11-05","capabilities":{},"clientInfo":{"name":"test","version":"0.1.0"}}}' \
  '{"jsonrpc":"2.0","method":"notifications/initialized"}' \
  '{"jsonrpc":"2.0","id":2,"method":"tools/call","params":{"name":"doctor","arguments":{}}}' \
  | ./dist/mcp-sandboxed-git-gh-cli

Test allowlist rejection

printf '%s\n' \
  '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2024-11-05","capabilities":{},"clientInfo":{"name":"test","version":"0.1.0"}}}' \
  '{"jsonrpc":"2.0","method":"notifications/initialized"}' \
  '{"jsonrpc":"2.0","id":2,"method":"tools/call","params":{"name":"git","arguments":{"args":["daemon"]}}}' \
  | ./dist/mcp-sandboxed-git-gh-cli

Replace ./dist/mcp-sandboxed-git-gh-cli with bun run src/index.ts for development testing.

Security policy

Commands run via execFile (no shell). Arguments are passed as an array, so shell metacharacters like ;, &&, $(), and backticks are treated as literal strings -- no command injection is possible.

Beyond that, the server enforces a configurable security policy that validates git/gh arguments per subcommand. The default policy is secure out of the box. Users can widen permissions by supplying a custom policy file via --policy <path>.

Default policy

The default policy ships with the server and is applied when no --policy flag is provided. Each subcommand is either unrestricted (true), disabled (false), or has specific constraints.

Rule types:

#### Git subcommands

Global: -c flag blocked at top level (prevents git -c core.hooksPath=... commit)

#### GH subcommands

Custom policy

To override specific defaults, create a JSON file and pass it via --policy:

claude mcp add -s user -t stdio mcp-sandboxed-git-gh-cli \
  /absolute/path/to/dist/mcp-sandboxed-git-gh-cli \
  -- --policy /path/to/policy.json

Or in .mcp.json:

{
  "mcpServers": {
    "mcp-sandboxed-git-gh-cli": {
      "command": "/absolute/path/to/dist/mcp-sandboxed-git-gh-cli",
      "args": ["--policy", "./security-policy.json"]
    }
  }
}

The custom policy is deep-merged over the defaults -- you only need to specify the entries you want to change. Everything else keeps its default.

Examples:

Allow git clean without --dry-run:

{
  "git": { "subcommands": { "clean": true } }
}

Allow gh api writes:

{
  "gh": { "subcommands": { "api": true } }
}

Enable gh codespace:

{
  "gh": { "subcommands": { "codespace": true } }
}

Allow git config to write any key:

{
  "git": { "subcommands": { "config": true } }
}

Restrict git config writes to a custom set of keys:

{
  "git": {
    "subcommands": {
      "config": {
        "readOnly": true,
        "safeWriteKeys": ["user.name", "user.email", "core.autocrlf"]
      }
    }
  }
}

Remove the -c global flag restriction:

{
  "git": { "blockedGlobalFlags": [] }
}

Project structure

src/
  index.ts          Server setup, probe-then-register flow, stdio transport
  executor.ts       execFile wrapper with policy enforcement, timeout, stdin, output cap
  policy.ts         SecurityPolicy types, DEFAULT_POLICY, load/merge
  sanitizer.ts      Policy-driven argument validator (sanitizeArgs)
  allowlist.ts      Derives allowed subcommand sets from policy (backward compat)
  config.ts         CLI argument parsing (--cwd, --policy, --git-timeout, etc.)
  probe.ts          Startup probes for binaries, identity, SSH, gh auth
  probe-helpers.ts  Probe utilities (git config reads, defaults)
  format.ts         Output formatting (ANSI stripping, truncation)
  doctor.ts         Doctor tool registration and diagnostic formatting
  onboard.ts        Onboard tool for guided setup
  constants.ts      Shared constants (timeouts, env key mappings)
dist/
  mcp-sandboxed-git-gh-cli   Compiled standalone binary

License

MIT