The ShadowGit MCP Server provides AI assistants with secure read-only access to ShadowGit repositories and organized commit management through session-based workflows.
Discover repositories: List all available ShadowGit-tracked repositories
Execute read-only git commands: Run safe git operations like log, diff, blame, and status to inspect repository history, analyze code evolution, and debug changes
Manage AI work sessions: Start sessions to pause auto-commits, create organized checkpoint commits with custom titles and AI authorship, and end sessions to reactivate automatic tracking
Follow secure workflow: Enforce a structured process (start_session → make changes → checkpoint → end_session) with built-in protections against write operations, destructive commands, path traversal, and command injection
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.
A Model Context Protocol (MCP) server that provides AI assistants with secure git access to your ShadowGit repositories, including the ability to create organized commits through the Session API. This enables powerful debugging, code analysis, and clean commit management by giving AI controlled access to your project's git history.
ShadowGit automatically captures every save as a git commit while also providing a Session API that allows AI assistants to pause auto-commits and create clean, organized commits. The MCP server provides both read access to your detailed development history and the ability to manage AI-assisted changes properly.
Related MCP server: GitHub Repo Explainer MCP
npm install -g shadowgit-mcp-server# Add to Claude Code
claude mcp add shadowgit -- shadowgit-mcp-server
# Restart Claude Code to load the serverAdd to your Claude Desktop MCP configuration:
macOS/Linux: ~/.config/Claude/claude_desktop_config.json
Windows: %APPDATA%\\Claude\\claude_desktop_config.json
{
"mcpServers": {
"shadowgit": {
"command": "shadowgit-mcp-server"
}
}
}Node.js 18+
ShadowGit app installed and running with tracked repositories
Session API requires ShadowGit version >= 0.3.0
Git available in PATH
MCP servers are stateless and use stdio transport:
The server runs on-demand when AI tools (Claude, Cursor) invoke it
Communication happens via stdin/stdout, not HTTP
The server starts when needed and exits when done
No persistent daemon or background process
You can configure the server behavior using these optional environment variables:
SHADOWGIT_TIMEOUT - Command execution timeout in milliseconds (default: 10000)
SHADOWGIT_SESSION_API - Session API URL (default: http://localhost:45289/api)
SHADOWGIT_LOG_LEVEL - Log level: debug, info, warn, error (default: info)
SHADOWGIT_HINTS - Set to 0 to disable workflow hints in git command outputs (default: enabled)
Example:
export SHADOWGIT_TIMEOUT=30000 # 30 second timeout
export SHADOWGIT_LOG_LEVEL=debug # Enable debug logging
export SHADOWGIT_HINTS=0 # Disable workflow banners for cleaner outputThe Session API (requires ShadowGit >= 0.3.0) allows AI assistants to temporarily pause ShadowGit's auto-commit feature and create clean, organized commits instead of having fragmented auto-commits during AI work.
IMPORTANT: AI assistants MUST follow this four-step workflow when making changes:
start_session({repo, description}) - Start work session BEFORE making changes (pauses auto-commits)
Make your changes - Edit code, fix bugs, add features
checkpoint({repo, title, message?, author?}) - Create a clean commit AFTER completing work
end_session({sessionId, commitHash?}) - End session when done (resumes auto-commits)
This workflow ensures AI-assisted changes result in clean, reviewable commits instead of fragmented auto-saves.
list_repos()Lists all ShadowGit-tracked repositories.
await shadowgit.list_repos()git_command({repo, command})Executes read-only git commands on a specific repository.
// View recent commits
await shadowgit.git_command({
repo: "my-project",
command: "log --oneline -10"
})
// Check what changed recently
await shadowgit.git_command({
repo: "my-project",
command: "diff HEAD~5 HEAD --stat"
})
// Find who changed a specific line
await shadowgit.git_command({
repo: "my-project",
command: "blame src/auth.ts"
})start_session({repo, description})Starts an AI work session using the Session API. This pauses ShadowGit's auto-commit feature, allowing you to make multiple changes that will be grouped into a single clean commit.
const result = await shadowgit.start_session({
repo: "my-app",
description: "Fixing authentication bug"
})
// Returns: Session ID (e.g., "mcp-client-1234567890")checkpoint({repo, title, message?, author?})Creates a checkpoint commit to save your work.
// After fixing a bug
const result = await shadowgit.checkpoint({
repo: "my-app",
title: "Fix null pointer exception in auth",
message: "Added null check before accessing user object",
author: "Claude"
})
// Returns formatted commit details including the commit hash
// After adding a feature
await shadowgit.checkpoint({
repo: "my-app",
title: "Add dark mode toggle",
message: "Implemented theme switching using CSS variables and localStorage persistence",
author: "GPT-4"
})
// Minimal usage (author defaults to "AI Assistant")
await shadowgit.checkpoint({
repo: "my-app",
title: "Update dependencies"
})end_session({sessionId, commitHash?})Ends the AI work session via the Session API. This resumes ShadowGit's auto-commit functionality for regular development.
await shadowgit.end_session({
sessionId: "mcp-client-1234567890",
commitHash: "abc1234" // Optional: from checkpoint result
})Parameters:
repo (required): Repository name or full path
title (required): Short commit title (max 50 characters)
message (optional): Detailed description of changes
author (optional): Your identifier (e.g., "Claude", "GPT-4", "Gemini") - defaults to "AI Assistant"
Notes:
Sessions prevent auto-commits from interfering with AI work
Automatically respects .gitignore patterns
Creates a timestamped commit with author identification
Will report if there are no changes to commit
Read-only access: Only safe git commands are allowed
No write operations: Commands like commit, push, merge are blocked
No destructive operations: Commands like branch, tag, reflog are blocked to prevent deletions
Repository validation: Only ShadowGit repositories can be accessed
Path traversal protection: Attempts to access files outside repositories are blocked
Command injection prevention: Uses execFileSync with array arguments for secure execution
Dangerous flag blocking: Blocks --git-dir, --work-tree, --exec, -c, --config, -C and other risky flags
Timeout protection: Commands are limited to prevent hanging
Enhanced error reporting: Git errors now include stderr/stdout for better debugging
When using ShadowGit MCP Server, AI assistants should:
Follow the workflow: Always: start_session() → make changes → checkpoint() → end_session()
Use descriptive titles: Keep titles under 50 characters but make them meaningful
Always create checkpoints: Call checkpoint() after completing each task
Identify yourself: Use the author parameter to identify which AI created the checkpoint
Document changes: Use the message parameter to explain what was changed and why
End sessions properly: Always call end_session() to resume auto-commits
// 1. First, check available repositories
const repos = await shadowgit.list_repos()
// 2. Start session BEFORE making changes
const sessionId = await shadowgit.start_session({
repo: "my-app",
description: "Refactoring authentication module"
})
// 3. Examine recent history
await shadowgit.git_command({
repo: "my-app",
command: "log --oneline -5"
})
// 4. Make your changes to the code...
// ... (edit files, fix bugs, etc.) ...
// 5. IMPORTANT: Create a checkpoint after completing the task
const commitHash = await shadowgit.checkpoint({
repo: "my-app",
title: "Refactor authentication module",
message: "Simplified login flow and added better error handling",
author: "Claude"
})
// 6. End the session when done
await shadowgit.end_session({
sessionId: sessionId,
commitHash: commitHash // Optional but recommended
})// Find what broke in the last hour
await shadowgit.git_command({
repo: "my-app",
command: "log --since='1 hour ago' --oneline"
})// See how a function evolved
await shadowgit.git_command({
repo: "my-app",
command: "log -L :functionName:src/file.ts"
})// Compare activity across projects
const repos = await shadowgit.list_repos()
for (const repo of repos) {
await shadowgit.git_command({
repo: repo.name,
command: "log --since='1 day ago' --oneline"
})
}Ensure ShadowGit app is installed and has tracked repositories
Check that ~/.shadowgit/repos.json exists
Use list_repos() to see exact repository names
Ensure the repository has a .shadowgit.git directory
Verify git is installed: git --version
Only read-only commands are allowed
Use absolute paths or repository names from list_repos()
Check error output which now includes stderr details for debugging
Set SHADOWGIT_HINTS=0 environment variable to disable workflow banners
This provides cleaner output for programmatic use
If you see "Session API is offline. Proceeding without session tracking":
The ShadowGit app may not be running
Sessions won't be tracked but git commands will still work
Auto-commits won't be paused (may cause fragmented commits)
Make sure ShadowGit app is running
Go in ShadowGit settings and check that the Session API is healthy
For contributors who want to modify or extend the MCP server:
# Clone the repository (private GitHub repo)
git clone https://github.com/shadowgit/shadowgit-mcp-server.git
cd shadowgit-mcp-server
npm install
# Build
npm run build
# Test
npm test
# Run locally for development
npm run dev
# Test the built version locally
node dist/shadowgit-mcp-server.js# Update version
npm version patch # or minor/major
# Build and test
npm run build
npm test
# Publish to npm (public registry)
npm publishMIT License - see LICENSE file for details.
Transform your development history into a powerful AI debugging assistant! 🚀
Create a git commit with your changes. Call this AFTER completing your work but BEFORE end_session. Creates a clean commit for the user to review.
| Name | Required | Description | Default |
|---|---|---|---|
| repo | Yes | Repository name | |
| title | Yes | Commit title (max 50 chars) - REQUIRED. Be specific about what was changed. | |
| message | No | Detailed commit message (optional, max 1000 chars) | |
| author | No | Author name (e.g., "Claude", "GPT-4"). Defaults to "AI Assistant" |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description must carry the behavioral burden. It mentions creating a 'clean commit for the user to review', hinting at intent, but doesn't disclose whether the commit is pushed to remote, what happens if there are no changes, or other side effects.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is two concise sentences, front-loaded with the core action and followed by critical timing guidance. Every word contributes to the purpose.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple commit tool with fully documented parameters, the description provides sufficient context: clear purpose, timing, and user-review intent. The only notable gap is the absence of output/result information, but the operation's outcome is self-evident.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, with each parameter described. The description adds no additional parameter-level meaning beyond the schema's existing descriptions, so it stays at the baseline 3.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description explicitly states 'Create a git commit with your changes', which is a specific verb+resource. It distinguishes itself from siblings by positioning itself as the pre-end_session commit step, separate from generic git_command.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
It gives explicit timing instructions: 'Call this AFTER completing your work but BEFORE end_session'. This clearly tells the agent when to use it, though it doesn't explicitly contrast with git_command for arbitrary git operations.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
End your work session to resume ShadowGit auto-commits. MUST be called AFTER checkpoint to properly close your work session.
| Name | Required | Description | Default |
|---|---|---|---|
| sessionId | Yes | Session ID from start_session | |
| commitHash | No | Commit hash from checkpoint (optional) |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations exist, so the description carries the burden. It discloses that ending the session resumes auto-commits and that proper closure requires prior checkpoint, but does not detail side effects or error conditions. This is minimal but not absent.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Two sentences, both essential: one defines purpose and effect, the other provides mandatory ordering. No filler.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple two-parameter tool without output schema, the description covers purpose, ordering, and consequence. It doesn't describe return values, but that's not expected given the schema and sibling context.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, with both sessionId and commitHash already described in the schema. The description adds no new parameter-level information, so baseline 3 applies.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool ends the work session and resumes auto-commits, using a specific verb and resource. It distinguishes from siblings (start_session, checkpoint) by focusing on session termination.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicitly states it MUST be called after checkpoint, providing clear ordering guidance. This implies when to use it and establishes a workflow context with sibling tools.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Execute a read-only git command on a ShadowGit repository. Only safe, read-only commands are allowed.
| Name | Required | Description | Default |
|---|---|---|---|
| repo | Yes | Repository name (use list_repos to see available repositories) | |
| command | Yes | Git command to execute (e.g., "log -10", "diff HEAD~1", "status") |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the burden of behavioral disclosure. It explicitly states the read-only, safe nature, which is a key behavioral trait, but it does not disclose what happens if an unsafe command is attempted, error behavior, or output format. This is adequate but not rich.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single sentence that immediately conveys the tool's purpose and key restriction. Every word is purposeful, with no redundancy or filler, making it highly efficient.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The tool is relatively simple (two string params, no output schema), and the description communicates the core read-only constraint. However, it omits any mention of return values, command whitelist specifics, or error handling, which would be useful given the lack of annotations. It is minimally complete but could be more thorough.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema fully documents both parameters with descriptions and examples (e.g., 'log -10', 'diff HEAD~1'). The description adds no extra semantic detail beyond reasserting read-only constraints, so it does not compensate beyond the schema's 100% coverage.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool's function: 'Execute a read-only git command on a ShadowGit repository.' This specifies a concrete action (execute) and resource (git command on a repository), and the read-only distinction sets it apart from siblings like list_repos or session management tools.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description notes that only 'safe, read-only commands are allowed,' implying it should be used for non-mutating operations. However, it does not explicitly provide when-to-use guidance or contrast with alternative tools, leaving the usage context somewhat implicit.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
List all available ShadowGit repositories. Use this first to discover which repositories you can work with.
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the full burden of behavioral disclosure. It implies a read-only, non-destructive operation by stating 'List' and 'Use this first', but it doesn't explicitly state that it has no side effects or return format. For a simple list tool, this is minimally adequate but lacks detailed behavioral context.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single concise sentence of 14 words. It is front-loaded with the tool's purpose and includes a usage hint. Every word contributes to the meaning, with no redundancy or filler.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's simplicity (no parameters, no output schema, no annotations), the description is sufficient. It clearly states what the tool does and when to use it relative to siblings. It doesn't describe return values, but for a straightforward listing tool, that is likely self-evident.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema has zero parameters, and the schema coverage is trivially 100%. According to the rubric, a baseline of 4 applies for zero parameters since there are no parameter semantics to explain. The description adds no parameter information, but none is needed.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool 'List all available ShadowGit repositories' with a specific verb (list) and resource (repositories). It also indicates its role as the initial discovery step ('Use this first'), which distinguishes it from sibling tools like git_command or session management.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description explicitly says 'Use this first to discover which repositories you can work with', providing clear context for when to utilize this tool. It doesn't mention when not to use it or alternatives, but for a discovery tool this is sufficient guidance.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Start a work session. MUST be called BEFORE making any changes. Without this, ShadowGit will create fragmented auto-commits during your work!
| Name | Required | Description | Default |
|---|---|---|---|
| repo | Yes | Repository name | |
| description | Yes | What you plan to do in this session |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the full burden of behavioral disclosure. It reveals a critical behavioral trait: without starting a session, ShadowGit creates fragmented auto-commits. This is valuable context beyond the tool's name, though it does not cover other aspects like authentication or side effects.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is two sentences long, front-loaded with the core purpose, and every sentence earns its place. The critical warning is emphasized in caps, making it highly scannable without unnecessary verbosity.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple tool with two required parameters and no output schema, the description covers the essential context: when to call it and the consequence of not doing so. It does not explain internal session mechanics, but that is unnecessary given the schema and sibling tools. It is sufficiently complete for an agent to select and invoke it correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema covers both parameters with clear descriptions ('Repository name' and 'What you plan to do in this session'), so schema coverage is 100%. The description adds no additional parameter-level information, which aligns with the baseline score of 3 for high schema coverage.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool's purpose with a specific verb and resource: 'Start a work session.' It also distinguishes from siblings by emphasizing the prerequisite role ('MUST be called BEFORE making any changes') and the consequence of skipping it, which sets it apart from end_session and git_command.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides an explicit when-to-use guideline: 'MUST be called BEFORE making any changes.' It also explains the negative outcome of not using it (fragmented auto-commits), giving clear context. However, it does not mention when not to use or point to alternatives, so it stops short of a 5.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
v1.0.0checkpointend_sessiongitgit_commandstart_sessiongitlist_reposScored across 5 tools
Each tool has a unique and distinct purpose: starting a session, creating a commit, ending a session, running read-only git commands, and listing repositories. No overlap or ambiguity.
All tool names use snake_case and follow a verb_noun pattern except 'git_command', which is slightly irregular but still clear. Overall consistent.
With 5 tools, the set is well-scoped for managing git sessions and repositories. It covers the essential operations without being excessive or insufficient.
The tools cover the full session lifecycle (start, commit, end) and provide a way to list repos and run read-only git commands. Missing explicit status or undo, but git_command can fill gaps.
Connect AI assistants to your GitHub-hosted Obsidian vault to seamlessly access, search, and analy…
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.
Connect AI assistants to GitHub - manage repos, issues, PRs, and workflows through natural language.
