> ## Documentation Index
> Fetch the complete documentation index at: https://docs.shadowgit.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Installation

> Set up ShadowGit MCP server in 2 minutes

## Prerequisites

Before you begin, make sure you have:

1. **Node.js 18+** installed ([Download Node.js](https://nodejs.org))
2. **ShadowGit desktop app** running with at least one tracked repository ([Download ShadowGit](https://shadowgit.com))
   * Available for Mac, Windows, and Linux
3. **An AI tool** like Claude Code or Cursor

## Install the MCP Server

### Option 1: npm (Recommended)

Open your terminal and run:

```bash theme={null}
npm install -g shadowgit-mcp-server
```

### Option 2: GitHub

Clone and install from the source:

```bash theme={null}
# 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:

<CardGroup cols={2}>
  <Card title="Claude Code" icon="asterisk" href="/ai-tools/claude-code">
    One-command setup for Claude Code
  </Card>

  <Card title="Cursor" icon="code-simple" href="/ai-tools/cursor">
    Complete Cursor configuration guide
  </Card>
</CardGroup>

## 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

```bash theme={null}
# 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

```bash theme={null}
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:**

```bash theme={null}
# Ubuntu/Debian
sudo apt update
sudo apt install libfuse2

# Fedora
sudo dnf install fuse fuse-libs

# Arch
sudo pacman -S fuse2
```

**Running the AppImage:**

```bash theme={null}
# 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:**

```bash theme={null}
# 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:

<CardGroup cols={2}>
  <Card title="Claude Code Guide" icon="asterisk" href="/ai-tools/claude-code">
    Detailed setup and usage with Claude Code
  </Card>

  <Card title="Cursor Guide" icon="code-simple" href="/ai-tools/cursor">
    Complete Cursor configuration and tips
  </Card>
</CardGroup>