MCP Git Status Server
A Model Context Protocol (MCP) server that provides git status and log functionality. This server allows MCP clients (like Claude Desktop, Cline, etc.) to check git repository status and view recent commit history.
Features
- Git Status Tool: Get the current status of a git repository
- Git Log Tool: View recent commit history
- Error Handling: Graceful error handling for non-git directories and other issues
- Directory Support: Optionally specify a directory path to check
Installation
- Clone or download this repository
- Install dependencies:
npm install
- Build the project:
npm run build
- Test the server:
npm test
Usage
Running the Server
The server communicates via stdio (standard input/output) as per MCP protocol:
# Run the built version
npm start
# Or run in development mode with tsx
npm run dev
Connecting to MCP Clients
Cursor IDE
Project-specific configuration (recommended for this project):
Cursor is already configured for this project via .cursor/mcp.json.
Global configuration (to use in all projects): The server is also configured globally. After restarting Cursor, you can ask questions like:
- "What's the git status of this repository?"
- "Show me the last 5 commits"
- "Check if there are any uncommitted changes"
Cursor will automatically use the git-status tools to answer your questions.
Manual configuration (if needed):
Create ~/.cursor/mcp.json with:
{
"mcpServers": {
"git-status": {
"command": "node",
"args": ["/Users/narayan/Developer/qoder/dist/index.js"],
"description": "Git status and log tools for repository management"
}
}
}
Note: Replace the path with the actual path to your compiled server.
Claude Desktop
Add this server to your Claude Desktop configuration file:
macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
Windows: %APPDATA%\Claude\claude_desktop_config.json
{
"mcpServers": {
"git-status": {
"command": "node",
"args": ["/path/to/your/mcp-git-status-server/dist/index.js"],
"description": "Git status and log tools for repository management"
}
}
}
Note: Replace /path/to/your/mcp-git-status-server with the actual path to your project directory.
A sample configuration file is included as claude-desktop-config.json for reference.
Other MCP Clients
For other MCP clients, configure them to run this server as a subprocess with stdio transport.
Available Tools
git-status
Get the current git status of a repository.
Parameters:
directory(optional): Directory path to check. Defaults to current directory.
Example usage in MCP client: "Check the git status of my project"
git-log
View recent git commit history.
Parameters:
directory(optional): Directory path to check. Defaults to current directory.count(optional): Number of recent commits to show. Defaults to 10.
Example usage in MCP client: "Show me the last 5 git commits"
Example Output
Git Status (clean repository)
Git Status for: /Users/username/my-project
Current branch: main
Status:
Working directory clean - no changes detected
Remotes:
origin https://github.com/username/my-project.git (fetch)
origin https://github.com/username/my-project.git (push)
Git Status (with changes)
Git Status for: /Users/username/my-project
Current branch: feature-branch
Status:
M src/index.ts
A src/new-file.ts
?? untracked.txt
Remotes:
origin https://github.com/username/my-project.git (fetch)
origin https://github.com/username/my-project.git (push)
Git Log
Recent Git Commits (5 most recent):
abc1234 Add new feature implementation
def5678 Fix bug in status handling
ghi9012 Update documentation
jkl3456 Initial commit
Error Handling
The server gracefully handles common error scenarios:
- Not a git repository: Provides clear error message
- Git not installed: Indicates git is not available
- Permission issues: Reports access problems
- Invalid directory: Handles non-existent paths
Development
Scripts
npm run build: Compile TypeScript to JavaScriptnpm run dev: Run in development mode with tsxnpm start: Run the compiled servernpm test: Build and validate the server functionality
Project Structure
├── src/
│ └── index.ts # Main server implementation
├── dist/ # Compiled JavaScript (generated)
├── validate-mcp.js # Validation script for testing
├── claude-desktop-config.json # Sample Claude Desktop configuration
├── package.json # Project configuration
├── tsconfig.json # TypeScript configuration
└── README.md # This file
Validation
The project includes a comprehensive validation script (validate-mcp.js) that tests:
- MCP protocol initialization
- Tool discovery (tools/list)
- Git status functionality
- Git log functionality
- Error handling for invalid tools
Run validation with:
npm test
The validation script will:
- Build the project
- Start the MCP server
- Test all functionality
- Report results
- Clean up automatically
Requirements
- Node.js 18.x or higher
- Git installed and available in PATH
- TypeScript (for development)
License
MIT License
Contributing
- Fork the repository
- Create a feature branch
- Make your changes
- Test thoroughly
- Submit a pull request
Troubleshooting
Server not starting:
- Check Node.js version (requires 18.x+)
- Ensure all dependencies are installed:
npm install - Build the project:
npm run build
Git commands failing:
- Verify git is installed:
git --version - Ensure you're in a git repository
- Check file permissions
MCP client not connecting:
- Verify the path to the server executable in client configuration
- Check that the server process can be started manually
- Review client logs for connection errors