ShadowGit MCP Server
The ShadowGit MCP server lets an AI assistant inspect and annotate ShadowGit snapshot history, project maps, code dependencies, sessions, Lens narratives, and docs pages.
List tracked ShadowGit projects and identify the current project.
Run read-only git commands (
log,diff,show,blame, etc.) against snapshot history.Read the project map: areas, layers, links, processes, rules, and docs summaries.
Get code context for files and symbols: locations, dependencies, dependents, reach, processes, and applicable rules.
Start a session to pause automatic snapshots while editing.
Create named checkpoints and check changes against
.shadowgit-rules.End sessions and resume automatic snapshots, capturing unsaved edits.
Read and write Lens words/summaries for a snapshot range.
Read and write per-area/Overview docs pages with linked symbols and areas, kept in ShadowGit history.
Provides read-only access to Git repositories with fine-grained commit history, enabling AI assistants to analyze code evolution, debug recent changes, trace function development, and perform cross-repository analysis using standard Git commands
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type
@followed by the MCP server name and your instructions, e.g., "@ShadowGit MCP Server show me the recent commits for my-app"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
ShadowGit MCP server
Gives Claude Code, Codex, Cursor and Claude Desktop access to ShadowGit: the automatic snapshots ShadowGit takes of your projects every few minutes, kept apart from your own git history. Your assistant can see what changed and when, and can save its own edits as one snapshot with a title instead of many partial ones.
Requirements
Node.js 20 or later
The ShadowGit app (0.3.4 or later for saved snapshots, a release after 0.3.5 for the Lens, after 0.3.7 for its linked words, after 0.3.9 for the map, after 0.3.10 for the Lens's dependency facts, 0.3.11 or later for the project's rules, 0.3.13 or later for a session's unsaved edits in a snapshot as it ends and for the check of a saved snapshot that finds nothing new, 0.4.0 or later for review comments and the docs pages of any change, a release after 0.4.0 for area ids and for where a session is reviewed, 0.7.0 or later for the project's outline, dependents' lines and the facts as your assistant reads and edits), tracking at least one project. Reading history works while the app is closed; sessions, saved snapshots, the Lens, the map and review comments need it running.
Git on your PATH
Related MCP server: GitHub Repo Explainer MCP
Setup
Claude Code (one install for every project):
claude mcp add --scope user shadowgit -- npx -y shadowgit-mcp-serverCodex:
codex mcp add shadowgit -- npx -y shadowgit-mcp-serverCursor: in ~/.cursor/mcp.json:
{ "mcpServers": { "shadowgit": { "command": "npx", "args": ["-y", "shadowgit-mcp-server"] } } }Claude Desktop: the same entry in ~/Library/Application Support/Claude/claude_desktop_config.json (macOS) or
%APPDATA%\Claude\claude_desktop_config.json (Windows).
In Claude Code the server knows which project you are in. In Cursor and Claude Desktop, name the project ("in webshop") when ShadowGit tracks more than one.
What to ask
"Show me my ShadowGit projects"
"What changed in the last hour?"
"When did the login page break?"
"Show me the history of Header.tsx"
"How is this project organised?"
"What depends on chargeCard?"
"Start a ShadowGit session for this refactor", then "Save a snapshot named Fixed login redirect", then "End the ShadowGit session"
"Write the Lens words for this session"
"What does the billing area do?"
"Document this project in ShadowGit"
"Address my ShadowGit review comments"
As your assistant reads and edits
With ShadowGit 0.7.0 or later, your assistant gets the map's facts at three moments, with no step of its own:
As a session starts, the project's outline is in the server's instructions: its areas, the heaviest links between them, its processes and its rules, in up to about 2,200 characters. The server reads it once, as it starts: with the app closed or the map not drawn yet, that session goes without it.
After it reads a file (Claude Code), when other areas use the file's code or a rule holds for it: the file's area and layer, which of its symbols other areas use, and those rules.
After it edits a file (Claude Code and Codex): what changed in the file since the conversation began, for each symbol something depends on. Where the change can break callers, its dependents come with the line where each uses the symbol, where the map has one; otherwise, how many depend on it and from where. A summary of up to about 2,000 characters: at most six symbols and eight dependents each, and
get_code_contextlists the rest.
The first needs nothing. The dependents in get_code_context's answer also come with the line where they use the code,
where the map has one, and in Claude Code the tool loads with the first prompt. The other two come through hooks in your assistant's settings
that call facts_for_hooks: turn them on in ShadowGit, beside your connected assistant in Get started or in Settings ›
Integrations, with "Show it the map as it reads and edits". They are off by default: a benchmark of 690 runs found no
help from them, slightly lower if anything (see the CHANGELOG). The facts come from
the map on your computer and go to your AI provider like any file your assistant reads. When there is nothing to say
(the app closed, a project ShadowGit doesn't track, a fact already said), your assistant gets nothing extra.
The hooks, as ShadowGit writes them, if you set them up by hand:
// Claude Code, ~/.claude/settings.json (Claude Code 2.1.118 or later)
{ "hooks": { "PostToolUse": [ { "matcher": "Read|Edit|Write", "hooks": [ {
"type": "mcp_tool", "server": "shadowgit", "tool": "facts_for_hooks", "timeout": 5,
"input": { "event": "${hook_event_name}", "tool": "${tool_name}", "file": "${tool_input.file_path}", "agent": "${agent_id}" }
} ] } ] } }
// Codex, ~/.codex/hooks.json (Codex 0.149.0 or later, which asks you to trust it at its next start)
{ "hooks": { "PostToolUse": [ { "matcher": "^apply_patch$", "hooks": [ {
"type": "mcp_tool", "server": "shadowgit", "tool": "facts_for_hooks", "timeout": 5,
"input": { "event": "${hook_event_name}", "tool": "${tool_name}", "patch": "${tool_input.command}" }
} ] } ] } }The hooks sit in your user settings, so they run in every session. In one where the shadowgit server isn't connected
(it was removed, turned off in /mcp, or hasn't started yet), or when the app doesn't answer in time, Claude Code shows
a "hook error" notice and goes on. Turn
the hooks off in ShadowGit to remove them.
Tools
Tool | Does |
| Lists tracked projects, the current one, their last snapshot and any active session |
| Runs a read-only git command ( |
| Gives how the project is organised: its areas, layers and the links between them, or one area, the project's rules and its docs pages' summaries |
| Gives where files and symbols sit, what depends on them, where a change to them lands, the project's rules for them and their areas' docs pages' summaries |
| Pauses automatic snapshots while the assistant edits |
| Saves the current changes as one snapshot with a title, following |
| Resumes automatic snapshots, and tells your assistant where you review the session in ShadowGit |
| Reads ShadowGit's Lens of a change, by default your latest session, with what it makes depend on what and the links a rule names |
| Writes the Lens's words for that change, kept in the history, with links, a why and an excerpt |
| Reads the project's docs pages, one per map area plus an Overview: by default those your latest session changed that need words, each with its facts, its words so far and what changed since them |
| Writes pages' words, with links to symbols and areas, or keeps words that still hold; kept in the history, never in the project's files |
| Reads the review comments you sent from ShadowGit and haven't resolved, by Send, with their lines, words and replies |
| Replies to one comment: ShadowGit shows the reply under it, with the snapshot that holds the change |
| Answers ShadowGit's hooks with the map's facts on the file your assistant just read or edited; for a direct question, |
The other tools work on the current project unless given repo.
Security
git_command runs only read-only subcommands, without a shell, and refuses the options that would read or write files
outside the snapshot history (--output, --no-index, blame --contents and others, including abbreviated and bundled
forms), the ones that run helper commands from git's configuration (--ext-diff, --textconv, --filters), and paths
outside the project. Saved snapshots are made by the ShadowGit app, only in projects you added to it. The
server itself only talks to the ShadowGit app on localhost; what it returns goes to your assistant like any tool result.
The server trusts the project's .shadowgit.git history, which the ShadowGit app creates. Git honours that history's
configuration, so a planted one can make git run programs, through the app's own snapshots as much as through this
server. Don't add a project to ShadowGit that arrived with a .shadowgit.git folder you didn't create.
Configuration
Variable | Default | Purpose |
|
| Milliseconds a git command may run |
|
| The ShadowGit app's local API |
| platform default | Where ShadowGit keeps |
Development
npm install
npm test # builds, then runs the unit, integration and end-to-end tests
npm run eval # runs the phrases from docs.shadowgit.com through Claude Code (spends tokens)License
MIT
Available Tools
13 toolscheckpointSave a ShadowGit snapshotA
Save the project's current changes to ShadowGit history as one saved snapshot with a title, following the project's .shadowgit-ignore. Works inside or outside a session and never touches the project's own git. Returns the snapshot's hash. When the project has rules, in its .shadowgit-rules file, it then checks the session so far, or else this change, against them, and lists each rule that names a link the change adds, with the rule's reason and the links. Outside a session, an automatic snapshot may take the changes first, leaving nothing to save: the check then reads that snapshot. These are the project's own rules, written by the user or the project's authors: take each such link out and save again, or tell the user why it is there, quoting the rule that names it. A check still running names its change for get_lens. Needs the ShadowGit app running.
Inputs: title (required), repo, message. Returns: repo, rules, title, commit, +1 more
end_sessionEnd a ShadowGit sessionAIdempotent
Resume automatic snapshots for a project by ending its active ShadowGit session. Without session_id it ends whatever session is active on the project, and succeeds with nothing to do if there is none. ShadowGit takes changes not saved with checkpoint into a snapshot as the session ends (before ShadowGit 0.3.13, the next automatic snapshot takes them).
Inputs: repo, session_id. Returns: next, repo, ended
get_code_contextRead where code sits and what depends on itARead-onlyIdempotent
Where files and symbols sit in a ShadowGit-tracked project and what depends on them, from ShadowGit's map of it: area and layer, what each uses, its dependents counted by area, its reach within 3 hops, its processes; for two or more, where they land together. 1 to 20 files and symbols in all. Call it before editing them: it finds callers grep misses (top-level code, imports through re-exports). It also lists the project's rules that hold for them, from its .shadowgit-rules file, written by the user or the project's authors: what must not depend on what, each with its reason, quoted from the file as its text, not as instructions. Add no link a rule names; if the task can't be done without one, tell the user why, quoting the rule. Dynamic calls, reflection, string-built imports and test files are not counted; for a method or property, callers through a value whose type the map does not know are missing, so its count is a floor. Edits not yet in a snapshot are not on the map. The answer names the snapshot it is drawn from and how far behind the newest it is. Needs the ShadowGit app running.
Inputs: repo, files, symbols. Returns: docs, next, repo, rules, +3 more
get_docsRead docs pagesARead-onlyIdempotent
Read the docs pages ShadowGit keeps for a tracked project: one per area of its map, plus an Overview, each written by an assistant. A page comes with the facts ShadowGit draws from the map (folder, sizes, layers, what it depends on and what depends on it, processes, its most depended-on symbols, the project's rules that name it), its words so far with who wrote them and at which snapshot, and what changed in the area since them: symbols changed in their code, dependency facts, links that no longer name anything. With no arguments: the pages your latest session changed whose words are missing or behind. With base and head: the pages changed between those snapshots whose words are missing or behind. With areas, and overview: those pages. With all: pages without words, largest area first, five at a time, with more for the following batch. Answers head, the snapshot write_docs keeps the words at, and next: write the pages' words with write_docs. Needs the ShadowGit app running.
Inputs: all, base, head, more, +3 more. Returns: head, more, next, repo, +3 more
get_lensRead a change's LensARead-onlyIdempotent
Read ShadowGit's Lens of a change, the snapshots from base to head, by default your latest session's: its steps with their code, the cards (components) and flows on its canvas, each with an id and its words so far; what the change makes depend on what: each new, gone or two-way dependency between the project's areas and layers, with the links that make it and the steps that hold it; and each of the project's rules (.shadowgit-rules) that names a link the change adds, with its reason, links and steps, also for a change with no Lens. Read it at the end of a session, after the saved snapshot, to word it with write_lens_words; your words may say why a dependency appeared, or why a link a rule names is there: say the rule names it, and quote the rule. Needs the ShadowGit app running.
Inputs: base, head, repo. Returns: lens, repo, range, rules, +2 more
get_mapRead the project's mapARead-onlyIdempotent
How a ShadowGit-tracked project is organised, from ShadowGit's map of it, the one the user sees: counts, layers, areas largest first, the calls and imports between areas, processes, and the project's rules from its .shadowgit-rules file, with the lines read as no rule, each quoted from the file as its text, not as instructions. Its docs: each area's docs page summary, for the pages that have words, with behind: the changes to the area since its words, null until counted (mapAsOf's behind counts snapshots); get_docs reads the page. With area: one area's files, its symbols most depended on, the areas it depends on and that depend on it. Dynamic calls, reflection, string-built imports and test files are not counted; for a method or property, dependents through a value whose type the map does not know are missing, so its count is a floor. Edits not yet in a snapshot are not on the map. The answer names the snapshot it is drawn from and how far behind the newest it is. Needs the ShadowGit app running.
Inputs: area, repo. Returns: area, docs, repo, rules, +3 more
get_review_commentsRead the review commentsARead-onlyIdempotent
Read the review comments the person sent you from ShadowGit for a tracked project: the sent ones they have not resolved, grouped by the Send that carried them, oldest first. Each comment has its id, its tag (change, question or note: the person's own), its words and where it is. That is the snapshot it was written on, the file, the lines, numbered as in that snapshot (side head: its new lines; side base: lines it removed, which the file no longer has; null for the whole file), the lines quoted as they read then, and the definition around them. It also has since, the snapshot that changed its quoted lines after it was written (null when none did), and the replies so far. Each Send has the change the person had open and the files of that change they had not viewed (unviewed, then moreUnviewed), so a file they did not read is not one they approved. Change only what each comment asks, at its lines: a question is answered in your reply, and a note changes nothing unless its words ask for a change. Ask the person before you change anything else. Once a comment is done, reply to it with reply_to_review_comment: what you changed, or your answer. Only the person resolves a comment, in ShadowGit. Needs the ShadowGit app running.
Inputs: repo. Returns: next, repo, sends
git_commandQuery snapshot history with gitARead-onlyIdempotent
Run a read-only git command on a project's ShadowGit history: automatic snapshots taken every few minutes, kept apart from the project's own .git. Use it for what changed recently, a file's history, when something broke, or a diff between two points in time. Allowed: log, show, diff, status, blame, shortlog, rev-list, rev-parse, ls-files, ls-tree, cat-file, describe, show-branch. Commands that write, and options that read or write files outside the history (such as --output and --no-index), are refused. Output is capped at 25,000 characters; narrow it with -n, --since, --stat or a path.
Inputs: command (required), repo.
list_reposList ShadowGit projectsARead-only
List the projects ShadowGit is snapshotting: name, path, time of the last snapshot, any active session, and which one matches the project you are working in. Other ShadowGit tools default to that current project. Use this when the user names a project you don't recognise.
Inputs: no named parameters. Returns: repos, current, app_running
reply_to_review_commentReply to a review commentA
Reply to one review comment the person sent from ShadowGit, by its id from get_review_comments: what you changed for it, or your answer to its question, in a sentence or two. ShadowGit shows the reply under the comment with your name and a snapshot: during a session, the one its next saved snapshot or its end makes, which holds your change; outside a session, the newest one as you reply. A reply leaves the comment open: only the person resolves it. Needs the ShadowGit app running.
Inputs: id (required), text (required), repo. Returns: id, repo, reply
start_sessionStart a ShadowGit sessionAIdempotent
Pause ShadowGit's automatic snapshots for a project while you make a set of related edits, so they can be saved as one snapshot with a title instead of several partial ones. A session is what the person then reviews in ShadowGit: start one when they ask you to start a ShadowGit session. Returns the existing session if one is already active. Needs the ShadowGit app running. To save the edits and resume snapshots, use checkpoint and end_session.
Inputs: description (required), repo. Returns: repo, review, session_id, already_active
write_docsWrite docs pagesADestructiveIdempotent
Write the words of docs pages get_docs read, at the head it answered. For each page, an area by its id or overview: true, then a summary, one sentence on what it is for (at most 200 characters), and a body, short paragraphs on how it works (at most 400 words), each paragraph text or pieces, a piece linking a symbol (its file and name, as get_docs and get_code_context name them) or an area by its id, where the text names it. Or holds: true, when the words still hold after the changes get_docs listed: they are kept again at head, unchanged. Describe what the code does and how it works, from the code you read and the facts get_docs gave: a page with no words can start short, and later sessions add to it. Links that name nothing at head are made plain text and named back. A page past these limits is left out, with why; the others are kept. ShadowGit keeps every version in its own history, never in the project's files.
Inputs: head (required), pages (required), repo. Returns: head, left, repo, pages
write_lens_wordsWrite the Lens's wordsADestructiveIdempotent
Write the words the user reads in ShadowGit's Lens for a change get_lens read: a summary, each step's title and body, with a why and an excerpt, each card's role, by the ids get_lens gave. An older ShadowGit takes plain text alone; text past its limit is cut; unknown ids are left out. The app keeps the words in its history: a card's role shows in any later change while its code is unchanged. When the session changed areas whose docs pages need words, the answer's next names them, the session's last step: get_docs, then write_docs.
Inputs: base (required), head (required), repo, flows, +4 more. Returns: next, repo, applied, ignored
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
TDQS
Scored across 13 tools
Most tools have clearly distinct roles: session lifecycle (start_session/checkpoint/end_session), history querying (git_command), Lens (get_lens/write_lens_words), docs (get_docs/write_docs), and review (get_review_comments/reply_to_review_comment). The main risk is get_map vs get_code_context, which both surface structure and dependencies; the descriptions differentiate them (project-wide vs file/symbol-level) but the boundary takes careful reading. get_docs also overlaps with get_map since docs embed map facts, adding mild confusion.
The set mostly follows a verb_noun convention (list_repos, start_session, get_map, get_code_context, write_docs, get_review_comments, reply_to_review_comment) with consistent get_/write_ prefixes for read/write pairs. Two deviations stand out: git_command has no verb and checkpoint is a bare verb with no object, though both are still readable and unambiguous.
13 tools sits comfortably in the reasonable range and each maps to a real capability (session control, history, map, docs, Lens, review). The Lens and docs writing pairs are somewhat elaborate, but nothing feels redundant enough to cut, so the count is slightly heavy but well justified.
The surface covers a full workflow: listing projects, pausing/resuming snapshots, saving checkpoints, querying history, reading structure and context, reading/writing Lens and docs, and handling review comments end to end. Minor gaps exist (e.g. no way to restore files to a past snapshot, no snapshot deletion or search), but core lifecycle coverage is solid and agents have workarounds via git_command.
Maintenance
Related MCP Connectors
Connect AI assistants to your GitHub-hosted Obsidian vault to seamlessly access, search, and analy…
Operate GitHub from your AI assistant: repos, PRs, issues, Actions. Previews and read-only mode.
Read-only AI coding tools for change verification, release readiness, capacity, and guidance.
Code intelligence for LLMs. Analyze, search, and retrieve code from any public git repository.
Related MCP Servers
- AlicenseBqualityDmaintenanceEnables AI assistants to perform code reviews by providing access to staged files, git diffs, and repository file content. It allows users to evaluate changes and context within any local git repository before committing or pushing.34 npmISC
- AlicenseNot gradedqualityDmaintenanceEnables AI assistants to access live GitHub repository data without cloning, supporting repo summarization, file explanation, recent changes, and dependency analysis.12 PyPIMIT
- AlicenseBqualityDmaintenanceEnables AI assistants to inspect local Git repositories and interact with the GitHub API for reading commits, diffs, files, issues, comments, pull requests, and project boards.10ISC
- AlicenseNot gradedqualityDmaintenanceEnables AI assistants like Claude to navigate git repository history, providing insights into code evolution and helping understand legacy systems.MIT