orbit-mcp

Use GitLab Orbit's local code graph from MCP clients on Windows and macOS, connected to a Linux development server over SSH.

This independent adapter runs the separately installed orbit CLI. It is not an official GitLab product and includes no GitLab source or binaries. Local queries need no GitLab account, API token, paid hosted graph, or GitLab server. Token savings depend on the task. See the benchmark methodology and the measured results linked there.

Tools

Context targets look like src/app.py, src/app.py:10-80, or symbol:calculate. Up to 20 targets can be read in one call. Bare files default to lines 1–200; explicit ranges allow up to 1000 lines. Symbols return their definition and indexed connections. Search defaults to literal text; regex mode excludes colons and definitions mode accepts names/words. These constraints prevent queries from switching to GitLab's remote target syntax.

Complete search results include matched. A true no-match result includes a short hint: definition misses recommend literal search or reading a known tracked file. The adapter does not issue a hidden fallback query. Truncated results do not claim whether matches exist, and command failures remain errors. Orbit 1.0 can return exit 1 for both no matches and operational failures: search stderr is captured separately, and exit 1 with any diagnostic is conservatively an error. This can also reject a harmless warning. Some invalid regexes produce an ordinary empty result with no diagnostics; matched:false means no match was reported, not that this adapter independently validated regex syntax.

Orbit may widen the optional search path scope when no matches are found. The configured repository, not that filter, is the access boundary.

Related MCP server: mcp-ssh-tool

Background indexing and status

Call orbit_index with {"repository":"myproject"}. It returns after Orbit's startup handshake, rather than waiting for the whole index. Repeated calls reuse an observed live worker; simultaneous starts may return busy. Then poll orbit_status for the same alias. Jobs survive MCP/SSH disconnects, and the next connection can inspect them. No extra daemon is installed.

Status distinguishes indexing/queued_or_indexing, indexed, stale, not_indexed, and unknown. It reports worker liveness separately from Orbit's saved manifest. PID identity includes process start time and boot ID, so a reused PID does not count as the original worker. dirty reports uncommitted/untracked files; working_tree_freshness remains unverified because Orbit exposes no full working-tree freshness fingerprint.

An indexed manifest does not prove the latest refresh succeeded. Orbit's detached child does not expose a recoverable exit code to this adapter. An unobserved worker or an interrupted startup is reported conservatively. Worker liveness refers to the last adapter request; a later external job may be running. An initially queued worker may have started, so its current phase is reported as queued_or_indexing. Check status before retrying a timed-out start; do not reset the graph. Use source queries to check the content you need. Progress percentages are unavailable.

Set background:false to use the original bounded foreground index command. The default changed to background indexing in 0.2.0.

Job observations live in $XDG_STATE_HOME/orbit-mcp (default ~/.local/state/orbit-mcp), or the configured state_dir. New directories and records are private. Connections must use the same Unix account, configuration, and Orbit data environment to share jobs. Status never returns another repository's manifest or raw index logs. Large workspace manifests may require raising max_output_bytes; truncated JSON is an error, not a partial status.

Install on the server

Requires Linux, Python 3.11+, Git, and a separately installed GitLab Orbit CLI under its applicable license. Tested with Orbit 1.0.0.

git clone https://github.com/akira69/orbit-mcp.git
cd orbit-mcp
python3 -m venv .venv
.venv/bin/pip install .
mkdir -p ~/.config/orbit-mcp
cp config.example.toml ~/.config/orbit-mcp/config.toml

Edit the local config: set the absolute Orbit executable path and map aliases to Git checkout roots. A repository needs an initial commit for Orbit indexing. Git worktrees are supported. Add each checkout explicitly; no home-directory discovery occurs. Keep real paths and credentials out of this repository.

/absolute/path/orbit-mcp/.venv/bin/orbit-mcp --config /absolute/path/config.toml

The process waits silently for MCP input. It needs no systemd service, background daemon, HTTP listener, or extra network port.

Diagnose a connection

orbit-mcp --config /absolute/path/config.toml --check

This prints JSON and exits 0 on success or 1 on failure. It checks executable version, repository roots and initial commits, writable adapter state, and a real MCP subprocess handshake with five-tool discovery and a repository-list call. It does not index or modify checkouts. Orbit 1.0.0 is the tested version; the report shows the installed version so upgrades can be assessed explicitly.

Run the same check over SSH from each desktop to verify that SSH route:

ssh -T -o BatchMode=yes orbit-devbox /absolute/path/orbit-mcp/.venv/bin/orbit-mcp --config /absolute/path/config.toml --check

A successful server-side check does not establish that a particular desktop app has loaded its MCP configuration. Restart that client and call orbit_repositories there too.

Connect from macOS or Windows

Your MCP client must support launching a stdio command; clients accepting only HTTP URLs cannot use this transport. The server remains Linux. The desktop needs OpenSSH and key-based access to that host.

Add an alias to ~/.ssh/config on macOS or %USERPROFILE%\.ssh\config on Windows:

Host orbit-devbox
    HostName devbox.example.net
    User your-user
    IdentityFile ~/.ssh/id_ed25519
    IdentitiesOnly yes
    BatchMode yes
    StrictHostKeyChecking yes

Replace the host, user, and key path. First establish and verify the host key interactively using your real hostname, then verify ssh orbit-devbox true. An encrypted key must be unlocked in the desktop's SSH agent. Do not disable host-key checks.

Add this to the client's MCP configuration, substituting the real server-side executable and config paths:

{
  "mcpServers": {
    "orbit-devbox": {
      "command": "ssh",
      "args": [
        "-T", "-o", "BatchMode=yes", "orbit-devbox",
        "/absolute/path/orbit-mcp/.venv/bin/orbit-mcp",
        "--config", "/absolute/path/config.toml"
      ]
    }
  }
}

Use launch paths without spaces, or a server-side wrapper. On Windows, if the app cannot find ssh, use C:\\Windows\\System32\\OpenSSH\\ssh.exe as the JSON command. Do not use -t: a pseudo-terminal corrupts MCP traffic. Noninteractive remote shell startup scripts must not print banners to stdout.

For Codex CLI, register the same command with:

codex mcp add orbit-devbox -- ssh -T -o BatchMode=yes orbit-devbox /absolute/path/orbit-mcp/.venv/bin/orbit-mcp --config /absolute/path/config.toml

Restart the client, then ask it to call orbit_repositories and query an alias. This reads the server's checkout. Laptop-only edits are invisible until copied or checked out there. Any reachable LAN/VPN SSH host works.

Limits and trust

• Configure only trusted checkouts intended for the client. Tracked secrets and indexed code are accessible. This is not a sandbox for hostile repositories or a multi-tenant authorization system.

• Use an SSH account with only the access it needs. MCP aliases do not restrict that account's ordinary SSH shell permissions.

• Context file targets must be tracked and resolve inside the selected root. Search follows Orbit's handling of working-tree and ignored files.

• No arbitrary shell, SQL, global graph IDs, or hosted GitLab targets.

• Commands serialize per connection; Orbit handles cross-process index locks. Timeouts and cancellation kill/reap the foreground command process group. Explicit background indexes survive disconnects. Use them for large repos; foreground timeout is configurable up to 600 seconds.

• Search/context/foreground-index responses contain output and truncated. Background/status responses contain state fields. Narrow queries when truncated. A truncated index response is not proof that indexing completed.

• GitLab API credential environment variables are removed from child processes; telemetry is disabled for each command. This is not a network sandbox: operator-managed Orbit/glab configuration still matters.

Update and test

git pull --ff-only
.venv/bin/pip install --upgrade .

Update Orbit separately. See compatibility notes. The upstream findings link prerelease issues and release notes to implemented safeguards and the next feature priorities.

.venv/bin/pip install -e '.[dev]'
.venv/bin/ruff check .
.venv/bin/pytest -q
ORBIT_INTEGRATION=1 .venv/bin/pytest -q

Default tests use a controlled executable fixture and real MCP stdio. The opt-in integration test uses real Orbit with a disposable Git repo and index, verifies background indexing across reconnects, search modes, caller context, and uncommitted-file refresh. scripts/probe_upstream.py records additional small language-resolution observations using disposable repositories. CI runs default tests on Python 3.11/3.13. This adapter is MIT licensed; Orbit is separate.