Skip to main content

​
Prerequisites

Before you begin, make sure you have:
  1. Node.js 18+ installed (Download Node.js)
  2. ShadowGit desktop app running with at least one tracked repository (Download ShadowGit)
    • Available for Mac, Windows, and Linux
  3. An AI tool like Claude Code or Cursor

​
Install the MCP Server

Open your terminal and run: 
npm install -g shadowgit-mcp-server

​
Option 2: GitHub

Clone and install from the source: 
# Clone the repository
git clone https://github.com/blade47/shadowgit-mcp.git
cd shadowgit-mcp

# Install dependencies and build
npm install
npm run build

# Install globally
npm install -g .
That’s it. The MCP server is now installed globally on your system.

​
Configure your AI tool

Once the MCP server is installed, you need to configure your AI assistant to use it. We have detailed guides for each tool:

Claude Code

One-command setup for Claude Code

Cursor

Complete Cursor configuration guide

​
What your AI can now do

Once configured, your AI assistant can use natural language to query your code history:

​
Basic Commands

List repositories: 
"Show me my ShadowGit repositories"
"List all tracked projects"
View recent changes: 
"Show me the last 10 commits in my-project"
"What changed in my-project in the last hour?"
"Show me the diff between HEAD and 5 commits ago"
Debug with history: 
"When did the login feature break?"
"Show me all changes to authentication.js today"
"What files were modified in the last 30 minutes?"

​
Session Management (New!)

Control auto-commits: 
"Start a ShadowGit session for debugging"
"Create a checkpoint with message 'Fixed auth bug'"
"End the current ShadowGit session"
Your AI will automatically use git commands like log, diff, show, and blame to answer your questions efficiently.

​
Troubleshooting

​
”No repositories found”

Your ShadowGit app needs to be tracking at least one repository.
  1. Open ShadowGit desktop app
  2. Click the ”+” button to add a repository
  3. Wait for the first snapshot to be created
  4. Try again in your AI tool

​
”Command not found: shadowgit-mcp-server”

The npm installation might not be in your PATH. Solution 1: Use the full path 
# Find where npm installed it
npm list -g shadowgit-mcp-server

# Use the full path in your config
"command": "/usr/local/bin/shadowgit-mcp-server"
Solution 2: Reinstall with npx 
npx shadowgit-mcp-server

​
”Repository not found”

Make sure you’re using the exact repository name from ShadowGit. First ask your AI to list repositories: 
"List my ShadowGit repositories"
This will show you the exact names to use. Then use the exact name when querying: 
"Show me the git log for my-project"
The repository name must match exactly what ShadowGit shows.

​
Claude/Cursor doesn’t see the MCP server

  1. Make sure you restarted the application after adding the config
  2. Check that Node.js is in your PATH: node --version
  3. Verify the server works manually: shadowgit-mcp-server --version

​
Linux-specific notes

​
Installing ShadowGit on Linux

ShadowGit is distributed as an AppImage for Linux, which works on all distributions. Prerequisites for AppImage: 
# Ubuntu/Debian
sudo apt update
sudo apt install libfuse2

# Fedora
sudo dnf install fuse fuse-libs

# Arch
sudo pacman -S fuse2
Running the AppImage: 
# Download the AppImage (choose your architecture)
# For Intel/AMD systems: ShadowGit-linux-x86_64-*.AppImage
# For ARM systems: ShadowGit-linux-arm64-*.AppImage

# Make it executable
chmod +x ShadowGit-linux-*.AppImage

# Run ShadowGit
./ShadowGit-linux-*.AppImage
Alternative if FUSE is not available: 
# Extract the AppImage
./ShadowGit-linux-*.AppImage --appimage-extract

# Run from extracted directory
./squashfs-root/AppRun

​
Data Locations on Linux

ShadowGit stores its data in the following locations:
  • Shadow repositories: ~/.shadowgit/
  • Application config: ~/.config/ShadowGit/
  • Logs: ~/.config/ShadowGit/logs/
  • Settings: ~/.config/ShadowGit/config.json
Make sure you have proper read/write permissions for these directories.

​
Security Notes

  • Read-only access: The MCP server can only read your git history, never modify it
  • Local only: No data is sent to any external servers
  • Safe commands only: Dangerous git commands are blocked (no push, merge, rebase)

​
Next Steps

Choose your AI tool to get started:

Claude Code Guide

Detailed setup and usage with Claude Code

Cursor Guide

Complete Cursor configuration and tips