MCP Git Repo Browser (Node.js)
A Node.js implementation of a Git repository browser using the Model Context Protocol (MCP).
Installation
NPM (Recommended)
npm install -g git-commands-mcp
Manual Installation
git clone https://github.com/bsreeram08/git-commands-mcp.git
cd git-commands-mcp
npm install
Configuration
Add this to your MCP settings configuration file:
{
"mcpServers": {
"git-commands-mcp": {
"command": "git-commands-mcp"
}
}
}
For manual installation, use:
{
"mcpServers": {
"git-commands-mcp": {
"command": "node",
"args": ["/path/to/git-commands-mcp/src/index.js"]
}
}
}
Features
The server provides the following tools:
Basic Repository Operations
-
git_directory_structure: Returns a tree-like representation of a repository's directory structure- Input: Repository URL
- Output: ASCII tree representation of the repository structure
-
git_read_files: Reads and returns the contents of specified files in a repository- Input: Repository URL and list of file paths
- Output: Dictionary mapping file paths to their contents
-
git_search_code: Searches for patterns in repository code- Input: Repository URL, search pattern, optional file patterns, case sensitivity, and context lines
- Output: JSON with search results including matching lines and context
Branch Operations
git_branch_diff: Compare two branches and show files changed between them- Input: Repository URL, source branch, target branch, and optional show_patch flag
- Output: JSON with commit count and diff summary
Commit Operations
-
git_commit_history: Get commit history for a branch with optional filtering- Input: Repository URL, branch name, max count, author filter, since date, until date, and message grep
- Output: JSON with commit details
-
git_commits_details: Get detailed information about commits including full messages and diffs- Input: Repository URL, branch name, max count, include_diff flag, author filter, since date, until date, and message grep
- Output: JSON with detailed commit information
-
git_local_changes: Get uncommitted changes in the working directory- Input: Local repository path
- Output: JSON with status information and diffs
Project Structure
git-commands-mcp/
├── src/
│ ├── index.js # Entry point
│ ├── server.js # Main server implementation
│ ├── handlers/ # Tool handlers
│ │ └── index.js # Tool implementation functions
│ └── utils/ # Utility functions
│ └── git.js # Git-related helper functions
├── package.json
└── readme.md
Implementation Details
- Uses Node.js native modules (crypto, path, os) for core functionality
- Leverages fs-extra for enhanced file operations
- Uses simple-git for Git repository operations
- Implements clean error handling and resource cleanup
- Creates deterministic temporary directories based on repository URL hashes
- Reuses cloned repositories when possible for efficiency
- Modular code structure for better maintainability
Requirements
- Node.js 14.x or higher
- Git installed on the system
Usage
If installed globally via npm:
git-commands-mcp
If installed manually:
node src/index.js
The server runs on stdio, making it compatible with MCP clients.
CI/CD
This project uses GitHub Actions for continuous integration and deployment:
Automatic NPM Publishing
The repository is configured with a GitHub Actions workflow that automatically publishes the package to npm when changes are pushed to the master branch.
Setting up NPM_AUTOMATION_TOKEN
To enable automatic publishing, you need to add an npm Automation token as a GitHub secret (this works even with accounts that have 2FA enabled):
-
Generate an npm Automation token:
- Log in to your npm account on npmjs.com
- Go to your profile settings
- Select "Access Tokens"
- Click "Generate New Token"
- Select "Automation" token type
- Set the appropriate permissions (needs "Read and write" for packages)
- Copy the generated token
-
Add the token to your GitHub repository:
- Go to your GitHub repository
- Navigate to "Settings" > "Secrets and variables" > "Actions"
- Click "New repository secret"
- Name:
NPM_AUTOMATION_TOKEN - Value: Paste your npm Automation token
- Click "Add secret"
Once configured, any push to the master branch will trigger the workflow to publish the package to npm.
License
MIT License - see the LICENSE file for details.