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 "Install 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 provided, so description carries burden. It mentions creating a clean commit for review but does not disclose side effects, permissions, or whether the commit is pushed. Adequate but could be more detailed.
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, front-loaded with purpose, followed by usage timing. No unnecessary words, efficient and well-structured.
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?
With no output schema and four parameters, the description provides clear context on purpose, timing, and output intent (commit for review). Slightly lacks details on whether commit is pushed or remote interaction.
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 description coverage is 100%, so baseline is 3. Description does not add additional meaning beyond schema for individual parameters; it only summarizes the overall action.
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?
Description clearly states 'Create a git commit with your changes' and provides context of usage ('AFTER completing your work but BEFORE end_session'). It distinguishes from siblings like end_session by specifying the order.
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 when to call the tool ('AFTER completing your work but BEFORE end_session'), providing temporal context. It does not explicitly list when not to use, but the positioning is clear.
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 are provided, so the description carries full responsibility. It hints at consequences via “MUST be called AFTER checkpoint” but does not detail side effects or error states if misused.
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: first states purpose, second gives a critical usage note. No extraneous words, front-loaded with the key action.
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 end tool with no output schema, the description covers the essential action and prerequisite. Could mention what happens if sessionId is invalid, but overall adequate.
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%, and the description adds context: sessionId comes from start_session, commitHash is optional from checkpoint. This aids understanding beyond the schema.
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 it ends the work session and resumes auto-commits. It distinguishes itself from siblings like ‘start_session’ (opposite) and ‘checkpoint’ (preceding step) 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 to call after checkpoint, providing clear ordering. Does not mention when not to use or list alternatives, but the directive is strong and sufficient.
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?
No annotations provided, so the description must disclose behavior. It states the tool is read-only and safe, which is the key behavioral trait. However, it lacks details on error handling, auth requirements, or output format.
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 concise sentences, front-loaded with action and constraint. Every word earns its place.
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 simplicity of the tool and no output schema, the description is fairly complete. It covers the main purpose and constraint, though it could mention output or error behavior.
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 good descriptions for both parameters. The description does not add additional meaning beyond what is in the schema, so a baseline score of 3 is appropriate.
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 verb 'Execute', the resource 'git command on a ShadowGit repository', and specifies the scope 'read-only' and 'safe'. This distinguishes it from sibling tools like checkpoint or start_session.
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 limits usage to read-only commands, which helps the agent decide when to use it. However, it does not explicitly mention when not to use it or provide alternatives among siblings.
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?
No annotations are provided. The description does not disclose traits like read-only or side effects, relying solely on implication. This is insufficient for full transparency.
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 clear, front-loaded sentences with no wasted words. Every part adds value.
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 no parameters, no output schema, and a simple purpose, the description is complete and sufficient for the agent to use the tool 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?
With zero parameters and 100% schema description coverage, the baseline is 4. No additional parameter info 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 lists all available ShadowGit repositories and is for initial discovery, distinguishing it from sibling tools that involve sessions and commands.
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 advises using this tool first for discovery, providing clear context. It does not list exclusions but the guidance is sufficient for a list tool.
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, the description carries full burden. It discloses that the tool is a setup action required before changes, and lack thereof leads to fragmented auto-commits. It does not detail session behavior or side effects, but is sufficient for a start session tool.
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 efficient sentences front-loaded with purpose, no redundant information.
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 description covers purpose and necessity, but lacks mention of return value and does not connect to sibling end_session for ending the session. Still fairly complete for a startup tool with no output schema.
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 descriptions for both repo and description. The description adds no extra meaning beyond 'what you plan to do' aligning with description parameter. Baseline 3 is appropriate.
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: 'Start a work session.' It also distinguishes this tool from siblings by emphasizing its prerequisite nature before making changes, which separates it from checkpoint, end_session, git_command, and list_repos.
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 explicit when-to-use guidance: 'MUST be called BEFORE making any changes.' It warns of consequences (fragmented auto-commits) if not used, but does not explicitly mention alternatives or when not to use.
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. Dates show when Glama detected each change.
v1.0.0checkpointend_sessiongitgit_commandstart_sessiongitlist_reposEach 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.
Unclaimed servers have limited discoverability.
If you are the server author, to access and configure the admin panel.
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.
We provide all the information about MCP servers via our MCP API.
curl -X GET 'https://glama.ai/api/mcp/v1/servers/aflsolutions/shadowgit-mcp'
If you have feedback or need assistance with the MCP directory API, please join our Discord server
