skipper

MCP server for working in a git repository: local git in-process, and GitHub, GitLab, Gitea, and Forgejo behind one small set of tools.

Why

The existing forge MCP servers expose the API, not a workflow. Counted from their own sources: GitHub's has ~125 tools, GitLab's ~88, Gitea's ~54. One tool per endpoint, three servers, three vocabularies, and an agent that has to work out which one it is talking to.

Skipper registers 20, and shows fewer than that: only the ones this repository can actually use, and the four that write only when you turn them on.

An agent does not need to be emperor of your forge. It does not need to create or destroy an organization on any given turn. It needs to know what this repository is, whether the build passed, and what broke. Skipper exposes that and skips the rest.

By default, no skipper tool can write to a forge. There is no create, delete, close, or fork, and out of the box no merge, push, fetch, or pull either: the only state any tool changes is local (staging, committing, local branches), so an agent cannot move a commit to a remote through skipper.

Merging and syncing are opt-in, in your global config only (~/.config/skipper/config.toml); a repository's own skipper.toml cannot turn them on:

[writes]
enabled = true   # show pr_merge, git_push, git_pull, git_fetch
confirm = true   # default: ask before each merge or push

With confirm, every merge and push is put to you through the client (MCP elicitation) with exactly what will happen, such as push master to github, origin or rebase #6 "chore: release 0.6.0" (release → master), and runs only if you approve. A client that cannot ask is refused; confirm = false lets writes run unattended. Even then nothing forces or deletes: +ref, a:b and -option refspecs are refused, and a merge is pinned to the head sha it was checked at, so a push in between fails it.

The destructive operations still exist in the CLIs. To delete a release, an agent calls gh directly, which your harness can allow or deny with one rule. That is one binary to gate instead of 267 tools to audit.

How it talks to things

Authentication

Local git needs no credentials: it reads and writes the repository directly, never the network.

For forges, skipper reuses the credentials the CLIs already hold. It stores no tokens of its own. Log in as usual:

gh auth login
glab auth login
tea login add

For GitHub, skipper asks gh auth token for the token once per host (it honours GH_TOKEN), keeps it in memory only, and calls the API itself: one HTTP request instead of a gh process per query. A 401 fetches the token again, so gh auth refresh or a rotated token needs no restart.

For Gitea and Forgejo, skipper reads the token from tea's config instead of running tea, which can block on an interactive prompt that never resolves under a non-interactive server. tea login add is still how you set it up.

Requirements

Building from source requires Rust 1.99 or newer. The repository pins Rust 1.99.0 for local and release builds.

Local git needs no binary: it runs in-process on gitoxide.

A missing, outdated, or unauthenticated CLI just hides that provider's tools. An auth check that fails on the network (timeout, connection reset) is not treated as logged out: skipper retries it with backoff for a few minutes and announces the tools with `tools/list_

... View full README on GitHub