Local Repo MCP 1.4.0

English | 简体中文

A focused, security-oriented MCP server for exactly one configured Git repository.

Primary constraint: provide only controlled repository access, allowlisted test/build/check execution, and verifiable result return. Keep the server lightweight, single-repository, and fixed-surface; do not evolve it into an Agent, orchestration platform, or general remote shell.

Capabilities

• Seven fixed MCP tools for file listing, UTF-8 reads, fixed-string search, filtered Git status/diff, atomic unified patches, and allowlisted verification commands.

• Three permission modes: read, write, and test.

• STDIO, OpenAI Secure MCP Tunnel, and Streamable HTTP transports.

• Remote HTTP through native HTTPS/mTLS or a trusted TLS-terminating reverse proxy.

• Bearer authentication, Host/Origin restrictions, bounded requests and outputs, sensitive-path filtering, audit records, and cross-process repository mutation locking.

• Desktop GUI with automatic configuration persistence. STDIO uses Connect; HTTP uses Start/Stop.

• Structured log center with MCP, Tunnel, Audit, and Security views; searchable readable summaries, raw JSON details, live refresh, credential redaction, and bounded rotation.

Related MCP server: codex-web-bridge

Start from a source checkout

Windows:

start_gui.bat

Linux/macOS:

./start_gui.sh

The bootstrap script creates .venv and refreshes dependencies whenever requirements.txt changes.

Package entry points

pip install .
local-repo-mcp-gui
local-repo-mcp

Installed and source-checkout layouts both use the packaged mcp_app.launcher; they do not depend on a repository-root wrapper being present.

Remote HTTP

Remote HTTP is not cloud-specific. It supports self-hosted servers, VMs, containers, Kubernetes, reverse proxies, and cloud load balancers.

Use either:

1. Native TLS with HTTP_TLS_CERTFILE and HTTP_TLS_KEYFILE; optionally set HTTP_TLS_CLIENT_CA for mTLS.

2. A trusted TLS reverse proxy with HTTP_TLS_TERMINATED_PROXY=true, HTTP_PUBLIC_URL=https://host/mcp, and explicit HTTP_PROXY_TRUSTED_IPS.

Wildcard bindings such as 0.0.0.0 are supported, but require an HTTPS HTTP_PUBLIC_URL whose path matches HTTP_PATH.

See docs/DEPLOYMENT.md and docs/SECURITY.md.

Tests

python -m pytest -q -p no:cacheprovider

Local Repo MCP never performs checkout, reset, rebase, merge, pull, push, or amend. Local git commit is off by default and requires an explicit GUI/ALLOW_GIT_COMMIT enablement in write or test mode.

Documentation

• Complete usage guide — installation, first launch, STDIO, Secure MCP Tunnel, Streamable HTTP, logs, testing, and troubleshooting.

• Deployment guide — native HTTPS, mTLS, reverse proxies, systemd, containers, and Kubernetes.

• Security model — repository boundary, HTTP controls, secrets, logs, and trusted test execution.

• Security policy — supported security boundary and issue reporting.

Requirements

• Python 3.11 or newer.

• Git available on PATH.

• One local Git working tree to expose.

• tunnel-client only when using OpenAI Secure MCP Tunnel.

Permission modes

Test mode executes repository code with the current operating-system user's permissions. It is not a sandbox and must be enabled only for trusted repositories.

MCP tools

repo_run_test keeps its historical tool name for client compatibility while delegating execution to the controlled command layer. The default allowlist includes python_pytest, go_test, go_build, go_vet, node_test, node_build, node_lint, maven_test, maven_build, gradle_test, and gradle_build.

Use command_key for one command. Use command_keys for a sequential batch of at most 8 commands. The complete batch is allowlist-validated before the first command starts; stop_on_failure=true stops on the first failure, while false continues through the remaining commands. This is bounded in-call execution, not a queue, scheduler, or background task system.

Every started command returns normalized evidence: command identity/kind, status, success, exit_code (with compatibility returncode), stdout/stderr plus truncation flags, and duration/timeout metadata. Timeout or output-limit termination remains a structured failed result with captured output. Command lifecycle metadata is logged, but stdout/stderr are not written to runtime/audit logs.

All eight public tools publish typed MCP input and output contracts. The server relies on MCP SDK structured-output generation instead of client-specific schema patches; GUI connection verification rejects missing/invalid tool schemas before accepting a connection. Optional collection inputs are represented as optional parameters with non-null array schemas rather than nullable unions.

src/tools/contracts.py is the single protocol-contract module for the public tool surface. Protocol regressions are tested against the actual MCPServer.list_tools() result, including the fixed eight-tool surface and presence of outputSchema for every tool.

First-use workflow

1. Start the GUI.

2. Select the target Git working tree.

3. Choose read, write, or test mode.

4. Choose STDIO or Streamable HTTP.

5. For STDIO, select Connect to verify MCP initialize, tool discovery, and repository identity.

6. For HTTP, configure the Bearer token, select Start, and then select Connect.

7. Copy the generated client configuration from the MCP Server page.

The complete usage guide contains the full STDIO, Tunnel, HTTP, logging, testing, and troubleshooting procedures.

ChatGPT and other MCP clients

Local Repo MCP can let ChatGPT build and maintain a local Git project within the selected permission mode. It is not limited to ChatGPT: other MCP-compatible coding agents, IDEs, desktop clients, and automation platforms can connect through STDIO or Streamable HTTP and receive the same tools and security controls.

For a new local project, select an empty directory in the GUI, explicitly confirm Git initialization, and use write or test mode. See Client compatibility and local project workflow.

Current GUI behavior: selecting a plain folder triggers a Git check and an explicit confirmation dialog. Accepting runs git init; declining leaves the folder unchanged. Initialization is never silent and does not create commits or remotes. A selected child directory inside a parent Git working tree cannot become a separate security boundary; the GUI asks to switch to the actual Git working-tree root.