# git-mcp-server

A secure, git-aware MCP server for working with local repositories inside LM Studio (or any MCP host).

## Features

- **Full file access** — read, write, edit, create, delete, move, search
- **Shell execution** — run commands in allowed directories with blocked dangerous patterns
- **Complete git workflow** — status, diff, log, branch, checkout, add, commit, push, pull, stash
- **Path sandboxing** — every operation is validated against your allowed directories; path traversal is blocked
- **No network calls** — inference stays local, this server never phones home

## Prerequisites

- Node.js 18+
- npm
- git

## Installation

```bash
# 1. Clone or copy this folder somewhere permanent
cd ~/tools
git clone <this-repo> git-mcp-server  # or just copy the folder

# 2. Install dependencies
cd git-mcp-server
npm install

# 3. Build
npm run build
```

After build, the server binary is at `dist/index.js`.

## Configure LM Studio

Open **Developer tab → Install → Edit mcp.json** in LM Studio and add:

```json
{
  "mcpServers": {
    "git-mcp": {
      "command": "node",
      "args": [
        "/absolute/path/to/git-mcp-server/dist/index.js",
        "--allow-dir", "/path/to/your/repo"
      ]
    }
  }
}
```

### Multiple repos

```json
{
  "mcpServers": {
    "git-mcp": {
      "command": "node",
      "args": [
        "/absolute/path/to/git-mcp-server/dist/index.js",
        "--allow-dir", "/home/user/projects/repo-one",
        "--allow-dir", "/home/user/projects/repo-two"
      ]
    }
  }
}
```

### Using environment variable instead

```json
{
  "mcpServers": {
    "git-mcp": {
      "command": "node",
      "args": ["/absolute/path/to/git-mcp-server/dist/index.js"],
      "env": {
        "ALLOWED_DIRS": "/home/user/projects/repo-one:/home/user/projects/repo-two"
      }
    }
  }
}
```

On Windows use `;` as the separator in `ALLOWED_DIRS`.

## Security model

| Layer | What it does |
|---|---|
| **Path sandboxing** | Every file/shell operation resolves the absolute path and checks it starts with an allowed dir. Path traversal (`../`) is blocked. |
| **Shell blocklist** | `rm -rf`, `sudo`, `mkfs`, `dd of=`, `curl \| sh`, `eval`, and similar patterns are rejected before execution. |
| **No root directories** | You must explicitly list allowed dirs — there is no "allow everything" mode. |
| **Delete is file-only** | `delete_file` refuses to delete directories; use `run_command` for that explicitly. |
| **LM Studio confirmation** | LM Studio shows a confirmation dialog for every tool call, so you review before anything executes. |

## Available tools

### File tools
| Tool | Description |
|---|---|
| `read_file` | Read a single file |
| `read_multiple_files` | Read several files in one call |
| `list_directory` | List entries in a directory |
| `directory_tree` | Recursive tree view (depth-limited) |
| `write_file` | Write / overwrite a file |
| `edit_file` | Targeted search-and-replace (returns diff) |
| `create_directory` | Create directory with parents |
| `delete_file` | Delete a file (not directories) |
| `move_file` | Move or rename within allowed dirs |
| `search_files` | Regex search across a directory |

### Shell
| Tool | Description |
|---|---|
| `run_command` | Run a shell command in an allowed directory |

### Git
| Tool | Description |
|---|---|
| `git_status` | Working tree status |
| `git_diff` | Diff working tree, index, or refs |
| `git_log` | Commit history |
| `git_branch` | List, create, delete, rename branches |
| `git_checkout` | Switch branches / create new ones |
| `git_add` | Stage files |
| `git_commit` | Commit staged changes |
| `git_push` | Push to remote |
| `git_pull` | Pull from remote (merge or rebase) |
| `git_stash` | Save, pop, list, or drop stashes |

## Example prompts

Once connected in LM Studio:

- *"Show me the status of the repo at ~/projects/myapp"*
- *"List all branches and tell me which has the most recent commit"*
- *"Read src/index.ts and refactor the error handling"*
- *"Stage all modified files and commit with the message 'fix: handle null case'"*
- *"Search for all usages of `fetchUser` across the repo"*
- *"Create a new branch called feature/auth and switch to it"*

## Recommended models for code work

Good tool-calling support is required. These work well locally:

- **Qwen3 8B / 14B** — excellent function calling, strong at code
- **Llama 4 Scout** — solid tool use, good multilingual support  
- **Mistral 7B Instruct** — fast, reliable for single-tool workflows

Q4_K_M quantization is the recommended starting point.