ShadowGit MCP Server
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.
What is ShadowGit?
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.
Installation
npm install -g shadowgit-mcp-server
Setup with Claude Code
# Add to Claude Code
claude mcp add shadowgit -- shadowgit-mcp-server
# Restart Claude Code to load the server
Setup with Claude Desktop
Add 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"
}
}
}
Requirements
- Node.js 18+
- ShadowGit app installed and running with tracked repositories
- Session API requires ShadowGit version >= 0.3.0
- Git available in PATH
How It Works
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
Environment Variables
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 to0to 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 output
Available Commands
Session Management
The 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 workend_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 pathtitle(required): Short commit title (max 50 characters)message(optional): Detailed description of changesauthor(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
.gitignorepatterns - Creates a timestamped commit with author identification
- Will report if there are no changes to commit
Security
- Read-only access: Only safe git commands are allowed
- No write operations: Commands like
commit,push,mergeare blocked - No destructive operations: Commands like
branch,tag,reflogare 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
execFileSyncwith array arguments for secure execution - Dangerous flag blocking: Blocks
--git-dir,--work-tree,--exec,-c,--config,-Cand other risky flags - Timeout protection: Commands are limited to prevent hanging
- Enhanced error reporting: Git errors now include stderr/stdout for better debugging
Best Practices for AI Assistants
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
authorparameter to identify which AI created the checkpoint - Document changes: Use the
messageparameter to explain what was changed and why - End sessions properly: Always call
end_session()to resume auto-commits
Complete Example Workflow
// 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
})
Example Use Cases
Debug Recent Changes
// Find what broke in the last hour
await shadowgit.git_command({
repo: "my-app",
command: "log --since='1 hour ago' --oneline"
})
Trace Code Evolution
// See how a function evolved
await shadowgit.git_command({
repo: "my-app",
command: "log -L :functionName:src/file.ts"
})
Cross-Repository Analysis
// 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"
})
}
Troubleshooting
No repositories found
- Ensure ShadowGit app is installed and has tracked repositories
- Check that
~/.shadowgit/repos.jsonexists
Repository not found
- Use
list_repos()to see exact repository names - Ensure the repository has a
.shadowgit.gitdirectory
Git commands fail
- 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
Workflow hints are too verbose
- Set
SHADOWGIT_HINTS=0environment variable to disable workflow banners - This provides cleaner output for programmatic use
Session API offline
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
Development
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
Publishing Updates
# Update version
npm version patch # or minor/major
# Build and test
npm run build
npm test
# Publish to npm (public registry)
npm publish
License
MIT License - see LICENSE file for details.
Related Projects
Transform your development history into a powerful AI debugging assistant! 🚀