git-simple-read-mcp

kajidog/git-simple-read-mcp

3.2

If you are the rightful owner of git-simple-read-mcp and would like to certify it and/or have it hosted online, please leave a comment on the right or send an email to henry@mcphub.com.

A Model Context Protocol (MCP) server designed for managing Git read operations within a specified workspace.

Tools
5
Resources
0
Prompts
0

Git Simple Read MCP

A Model Context Protocol (MCP) server for Git read operations with workspace management.

Features

This MCP server provides the following tools for Git repository read operations:

Workspace Management

  • clone_repository: Clone a Git repository into the managed workspace
  • list_workspace_repositories: List all repositories in the workspace
  • remove_repository: Remove a repository from the workspace

Security: All operations are restricted to repositories within the specified workspace directory.

Repository Information

  • get_repository_info: Get basic repository information including:
    • Commit count
    • Last update date
    • Current branch
    • License file detection
    • README content (first 50 lines)
    • Remote URL

Repository Operations

  • pull_repository: Execute git pull on the specified repository

Branch Management

  • list_branches: List all branches in the repository (supports pagination)
  • switch_branch: Switch to a specified branch

File Operations

  • search_files: Search for files containing specified keywords with enhanced filtering
    • AND/OR logic support
    • File pattern filtering (include/exclude patterns)
    • Context lines around matches
    • Filename and content search
  • list_files: List files in specified directory with enhanced information
    • Recursive expansion
    • File pattern filtering (include/exclude patterns)
    • Character count and line count for each file
    • File size information
  • get_file_content: Get the content of files
    • Single file or multiple files in one request
    • Individual error handling for each file
    • Line limits applied per file

Installation

  1. Clone this repository:
git clone <repository-url>
cd git-simple-read-mcp
  1. Build the project:
go build .

Usage

Standalone Server

Start the MCP server using stdio transport (default):

./git-simple-read-mcp mcp --workspace ./my-workspace

Start the MCP server using HTTP transport:

./git-simple-read-mcp mcp --transport http --port 8080 --workspace ./my-workspace

The workspace directory will be created automatically if it doesn't exist. All Git operations will be restricted to repositories within this workspace.

Remote MCP Usage

To use this as a remote MCP server:

1. Build and Start HTTP Server

# Build the server
go build .

# Start HTTP server (default port 8080)
./git-simple-read-mcp mcp --transport http --port 8080 --workspace ./workspace

# Or use the provided script
./start-server.sh ./workspace 8080

2. Configure MCP Client

Add to your MCP client configuration (e.g., Claude Code):

{
  "mcpServers": {
    "git-remote": {
      "url": "http://localhost:8080/mcp",
      "description": "Git Simple Read MCP Server for repository read operations"
    }
  }
}

3. Remote Access

For remote access across network:

# Start server on all interfaces
./git-simple-read-mcp mcp --transport http --port 8080 --workspace ./workspace --host 0.0.0.0

# Then connect from client with
# "url": "http://your-server-ip:8080/mcp"

Security Note: When exposing over network, consider adding authentication, HTTPS, and firewall rules.

4. Docker Deployment

Run with Docker:

# Build the image
docker build -t git-simple-read-mcp .

# Run the container
docker run -d \
  --name git-simple-read-mcp \
  -p 8080:8080 \
  -v $(pwd)/workspace:/workspace \
  git-simple-read-mcp

# Or use docker-compose
docker-compose up -d

5. Production Deployment

For systemd-based systems:

# Copy files to production location
sudo cp git-simple-read-mcp /opt/git-simple-read-mcp/
sudo cp git-simple-read-mcp.service /etc/systemd/system/

# Create user and directories
sudo useradd -r -s /bin/false git-mcp
sudo mkdir -p /var/lib/git-simple-read-mcp/workspace
sudo chown -R git-mcp:git-mcp /var/lib/git-simple-read-mcp

# Enable and start service
sudo systemctl daemon-reload
sudo systemctl enable git-simple-read-mcp
sudo systemctl start git-simple-read-mcp

Tool Parameters

Each tool accepts JSON parameters:

clone_repository
{
  "url": "https://github.com/user/repository.git",
  "name": "my-repo"
}
list_repositories
{}
remove_repository
{
  "name": "repository-name"
}
get_repository_info
{
  "repository": "my-repo"
}
pull_repository
{
  "repository": "my-repo"
}
list_branches
{
  "repository": "my-repo",
  "limit": 10
}
switch_branch
{
  "repository": "my-repo",
  "branch": "branch-name"
}
list_commits
{
  "repository": "my-repo",
  "limit": 20
}

Parameters:

  • limit: Maximum number of commits to return, default: 20
get_commit_diff
{
  "repository": "my-repo",
  "commit_hash": "a1b2c3d4"
}

Parameters:

  • commit_hash: The hash of the commit to get the diff for.
search_files
{
  "repository": "my-repo",
  "keywords": ["keyword1", "keyword2"],
  "search_mode": "and",
  "include_filename": false,
  "context_lines": 0,
  "include_patterns": ["*.go", "*.js"],
  "exclude_patterns": ["*_test.go", "vendor/*"],
  "limit": 20
}

Parameters:

  • keywords: Array of search terms
  • search_mode: "and" (all keywords) or "or" (any keyword), default: "and"
  • include_filename: Search in filenames too, default: false
  • context_lines: Lines of context around matches, default: 0
  • include_patterns: File patterns to include (glob format)
  • exclude_patterns: File patterns to exclude (glob format)
  • limit: Maximum results, default: 20
list_files
{
  "repository": "my-repo",
  "directory": "src",
  "recursive": true,
  "include_patterns": ["*.go", "*.js"],
  "exclude_patterns": ["*_test.go", "node_modules/*"],
  "limit": 50
}

Parameters:

  • directory: Target directory, default: "."
  • recursive: Include subdirectories, default: false
  • include_patterns: File patterns to include (glob format)
  • exclude_patterns: File patterns to exclude (glob format)
  • limit: Maximum files to return, default: 50

Output includes:

  • File path and name
  • Directory flag
  • File size (bytes/KB/MB)
  • Character count (for text files)
  • Line count (for text files)
  • Modification time
get_file_content

Single file:

{
  "repository": "my-repo",
  "file_path": "src/main.go",
  "max_lines": 100
}

Multiple files:

{
  "repository": "my-repo",
  "file_paths": ["src/main.go", "src/utils.go", "config.json"],
  "max_lines": 100
}

Parameters:

  • file_path: Single file path (for backward compatibility)
  • file_paths: Array of file paths (for multiple files)
  • max_lines: Maximum lines per file, default: 100

Multiple file output:

  • Individual success/error status per file
  • File path identification
  • Content or error message for each file

Enhanced Features Examples

File Pattern Filtering

List only Go files:

{
  "repository": "my-repo",
  "include_patterns": ["*.go"]
}

List all files except tests and vendor:

{
  "repository": "my-repo",
  "exclude_patterns": ["*_test.go", "vendor/*", "node_modules/*"]
}

Search for functions only in source files:

{
  "repository": "my-repo", 
  "keywords": ["func"],
  "include_patterns": ["src/*.go", "lib/*.go"],
  "exclude_patterns": ["*_test.go"]
}

Character Count and File Information

The list_files tool now returns detailed file information:

šŸ“„ main.go (2.1 KB, 156 chars, 8 lines)
šŸ“„ utils.go (1.5 KB, 98 chars, 5 lines)
šŸ“ src/
šŸ“„ src/app.js (856 bytes, 45 chars, 3 lines)

Multiple File Content Retrieval

{
  "repository": "my-repo",
  "file_paths": ["main.go", "config.json", "README.md"],
  "max_lines": 50
}

Returns content for all files with individual error handling:

Content of 3 files:
==================================================

šŸ“„ main.go

package main func main() {}


------------------------------------------

šŸ“„ config.json  
āŒ Error: file not found

------------------------------------------

šŸ“„ README.md

My Project

This is a sample project

Error Handling

All tools return appropriate error messages when:

  • Repository path is invalid or not a Git repository
  • Git commands fail
  • File operations encounter errors
  • Parameters are missing or invalid

Pagination

Several tools support pagination to prevent large outputs:

  • list_branches: Limit number of branches returned
  • search_files: Limit search results (default: 20)
  • list_files: Limit file listing (default: 50)
  • get_file_content: Limit lines read (default: 100)

Security Considerations

  • This server performs read-only operations on Git repositories
  • The switch_branch operation modifies the working directory but doesn't commit changes
  • The pull_repository operation updates the repository from its remote origin
  • Always ensure the server has appropriate permissions for the target repositories

Dependencies

License

This project is provided as-is for educational and development purposes.