Local Git MCP Server

A local Model Context Protocol (MCP) server for interacting with Git repositories. This server extends the mcp_server_git with custom tools for listing repository directories and viewing file contents, making it easier to navigate and inspect codebases programmatically.

---

✅ Features

• Custom Tools:

  • list_repo_dir: Recursively list files and directories in a Git repository. If no path is provided, it lists the root directory.
  • view_repo_file: Read and return the contents of a specific file in the repository.

• Git Integration: Inherits all standard Git operations from mcp_server_git (e.g., git_status, git_diff, git_log, etc.).

• Flexible Configuration: Supports environment variables for repository path configuration.

• MCP Compatibility: Works with any MCP-compatible client (e.g., Model Context Protocol clients).

---

🛠️ Prerequisites

Before running the server, ensure the following are installed:

1. Python 3.8+

• Download: Python Official Website
• Verify installation:

  python --version
  

2. pip (Python Package Manager)

• Ensure pip is installed and up-to-date:

  python -m pip install --upgrade pip
  

3. Required Python Packages

Install the dependencies using pip:

pip install starlette uvicorn mcp-server-git

4. Git

• Download: Git Official Website
• Verify installation:

  git --version
  

5. Target Git Repository

• Ensure the repository you want to interact with is cloned locally on your machine.
• By default, the server uses the path specified in the TARGET_REPO environment variable. If not set, it defaults to:

  C:\Users\bpweathe\code\SCIP\scipai
  

---

🚀 Installation & Setup

Step 1: Clone the Repository

git clone https://github.com/bpweatherill/local-git-mcp.git
cd local-git-mcp

Step 2: Install Dependencies

pip install -r requirements.txt

Note: If requirements.txt does not exist, install the required packages manually:

pip install starlette uvicorn mcp-server-git

Step 3: Configure the Target Repository

Set the TARGET_REPO environment variable to point to your local Git repository:

Windows (PowerShell)

$env:TARGET_REPO = "C:\path\to\your\repo"

macOS/Linux (Terminal)

export TARGET_REPO="/path/to/your/repo"

Tip: If you don’t set TARGET_REPO, the server will default to C:\Users\bpweathe\code\SCIP\scipai.

---

🏃 Running the Server

Start the MCP server using the following command:

python mcp_server.py

The server will start on:

• Host: localhost
• Port: 8808

You should see output similar to:

INFO:     Uvicorn running on http://localhost:8808 (Press CTRL+C to quit)

---

🛠️ Using the Server

Connecting with an MCP Client

Once the server is running, you can connect to it using any MCP-compatible client. Here’s how to test it:

1. List Root Directory

Call the list_repo_dir tool with no arguments to list the root of the repository:

{
  "method": "tools/call",
  "params": {
    "name": "list_repo_dir",
    "arguments": {}
  }
}

2. List a Subdirectory

Pass a relative path to list the contents of a subdirectory:

{
  "method": "tools/call",
  "params": {
    "name": "list_repo_dir",
    "arguments": {
      "path": "docs/clients"
    }
  }
}

3. View a File

Use the view_repo_file tool to read a file:

{
  "method": "tools/call",
  "params": {
    "name": "view_repo_file",
    "arguments": {
      "path": "README.md"
    }
  }
}

4. Standard Git Tools

The server also supports all standard Git tools from mcp_server_git. For example:

{
  "method": "tools/call",
  "params": {
    "name": "git_status",
    "arguments": {}
  }
}

---

📡 API Endpoints

The server exposes the following endpoints:

Endpoint	Method	Description
/	GET	SSE endpoint for streaming server events
/	POST	Messages endpoint for MCP tool calls
/sse	GET	Alternative SSE endpoint
/messages	POST	Alternative messages endpoint
/mcp	GET/POST	Unified MCP endpoint (SSE for GET, messages for POST)

---

🔧 Custom Tools

1. list_repo_dir

Description: Lists files and directories in a repository path.

Parameters:

• path (optional): Relative path of the subdirectory to list. If omitted, lists the root directory.

Example Output:

Items inside 'docs/clients':
- copilot-byok.md
- pageassist.md
- openai-api.md

---

2. view_repo_file

Description: Reads and returns the complete text contents of a file.

Parameters:

• path (required): Relative path of the file to view.

Example Output:

# README.md
This is the content of the README file...

---

📜 Standard Git Tools

The server inherits all tools from mcp_server_git, including:

• git_status: Show working tree status.
• git_diff: Show changes between branches or commits.
• git_log: Show commit history.
• git_add: Stage files for commit.
• git_commit: Commit changes to the repository.
• git_branch: List branches.
• git_reset: Unstage changes.

For a full list, call the tools/list method after connecting to the server.

---

🧪 Testing

To verify the server is working correctly, you can use a tool like curl or Postman to send a test request:

Example curl Request

curl -X POST http://localhost:8808/messages \
  -H "Content-Type: application/json" \
  -d '{
    "id": 1,
    "method": "tools/list",
    "params": {}
  }'

Expected Response:

{
  "jsonrpc": "2.0",
  "id": 1,
  "result": {
    "tools": [
      {
        "name": "list_repo_dir",
        "description": "Lists files and items inside a specific sub-folder of the repository.",
        "inputSchema": { ... }
      },
      {
        "name": "view_repo_file",
        "description": "Reads and returns the complete text contents of a specific file.",
        "inputSchema": { ... }
      },
      {
        "name": "git_status",
        "description": "Shows the working tree status.",
        "inputSchema": { ... }
      }
    ]
  }
}

---

🐛 Troubleshooting

Common Issues

1. Server Fails to Start

• Cause: Missing dependencies or incorrect Python version.
• Solution: Ensure Python 3.8+ and all required packages are installed:

  pip install starlette uvicorn mcp-server-git
  

2. Repository Not Found

• Cause: The TARGET_REPO path is incorrect or the repository does not exist.
• Solution: Set TARGET_REPO to the correct local path:

  # Windows (PowerShell)
  $env:TARGET_REPO = "C:\path\to\your\repo"
  
  # macOS/Linux
  export TARGET_REPO="/path/to/your/repo"
  

3. Permission Denied

• Cause: The server does not have read access to the repository.
• Solution: Ensure the repository is accessible and the server has read permissions.

4. Timeouts

• Cause: The server takes too long to respond.
• Solution: Check if the mcp_server_git subprocess is running correctly. Restart the server if needed.

---

📚 Example Use Cases

1. Navigate a Codebase

// List the root directory
{
  "method": "tools/call",
  "params": {
    "name": "list_repo_dir",
    "arguments": {}
  }
}

// List the 'src' directory
{
  "method": "tools/call",
  "params": {
    "name": "list_repo_dir",
    "arguments": {
      "path": "src"
    }
  }
}

// View a file
{
  "method": "tools/call",
  "params": {
    "name": "view_repo_file",
    "arguments": {
      "path": "src/main.py"
    }
  }
}

---

2. Check Git Status and Diffs

// Check Git status
{
  "method": "tools/call",
  "params": {
    "name": "git_status",
    "arguments": {}
  }
}

// Show unstaged changes
{
  "method": "tools/call",
  "params": {
    "name": "git_diff_unstaged",
    "arguments": {}
  }
}

---

🔒 Security Notes

• The server only allows access to files within the TARGET_REPO directory. Attempts to access files outside this path will result in a "Path out of bounds" error.
• Never expose this server to untrusted networks without proper authentication and authorization.

---

📜 License

This project is open-source and licensed under the MIT License.

---

🤝 Contributing

Contributions are welcome! Feel free to:

• Report bugs or suggest features by opening an issue.
• Submit pull requests with improvements.

---

📞 Support

For questions or issues:

• Check the GitHub Issues for known problems.
• Open a new issue if you encounter unexpected behavior.

---

🏷️ Tags

mcp-server, git, python, starlette, uvicorn, model-context-protocol