# Git MCP Server
A clean, modular Git MCP server supporting both GitHub and GitLab.
## Quick Start
### Claude Desktop Configuration
Add to your `claude_desktop_config.json`:
**macOS**: `~/Library/Application Support/Claude/claude_desktop_config.json`
**Windows**: `%APPDATA%\Claude\claude_desktop_config.json`
#### GitHub
```json
{
"mcpServers": {
"git": {
"command": "npx",
"args": ["-y", "@raytien/git-mcp-server"],
"env": {
"GIT_PROVIDER": "github",
"GIT_TOKEN": "ghp_xxxxxxxxxxxxxxxxxxxx"
}
}
}
}
```
#### GitHub Enterprise
```json
{
"mcpServers": {
"git": {
"command": "npx",
"args": ["-y", "@raytien/git-mcp-server"],
"env": {
"GIT_PROVIDER": "github",
"GIT_API_URL": "https://github.your-company.com/api/v3",
"GIT_TOKEN": "ghp_xxxxxxxxxxxxxxxxxxxx"
}
}
}
}
```
#### GitLab.com (SaaS)
```json
{
"mcpServers": {
"git": {
"command": "npx",
"args": ["-y", "@raytien/git-mcp-server"],
"env": {
"GIT_PROVIDER": "gitlab",
"GIT_TOKEN": "glpat-xxxxxxxxxxxxxxxxxxxx"
}
}
}
}
```
#### Self-Hosted GitLab
```json
{
"mcpServers": {
"git": {
"command": "npx",
"args": ["-y", "@raytien/git-mcp-server"],
"env": {
"GIT_PROVIDER": "gitlab",
"GIT_API_URL": "https://gitlab.your-company.com/api/v4",
"GIT_TOKEN": "glpat-xxxxxxxxxxxxxxxxxxxx"
}
}
}
}
```
#### Read-Only Mode
```json
{
"mcpServers": {
"git": {
"command": "npx",
"args": ["-y", "@raytien/git-mcp-server"],
"env": {
"GIT_PROVIDER": "github",
"GIT_TOKEN": "ghp_xxxxxxxxxxxxxxxxxxxx",
"GIT_READ_ONLY": "true"
}
}
}
}
```
### Get Your Token
#### GitHub
1. Go to GitHub > Settings > Developer settings > Personal access tokens > Tokens (classic)
2. Generate new token with scopes: `repo`, `read:org`, `workflow`
3. Copy the token (starts with `ghp_`)
#### GitLab
1. Go to GitLab > Settings > Access Tokens
2. Create a new token with scopes: `api`, `read_api`, `read_repository`, `write_repository`
3. Copy the token (starts with `glpat-`)
## Available Tools
### Repository
| Tool | Description |
| --------------------- | ------------------------------------ |
| `get_file_contents` | Read file content from repository |
| `get_repository_tree` | List directory structure |
| `push_files` | Push file changes in a single commit |
| `create_branch` | Create a new branch |
| `list_branches` | List repository branches |
| `list_commits` | List commit history |
| `search_code` | Search for code in repository |
### Issues
| Tool | Description |
| -------------- | ------------------ |
| `get_issue` | Get a single issue |
| `list_issues` | List issues |
| `create_issue` | Create a new issue |
| `update_issue` | Update an issue |
### Pull/Merge Requests
| Tool | Description |
| ------------------------ | ------------------------- |
| `get_pull_request` | Get a merge request |
| `list_pull_requests` | List merge requests |
| `create_pull_request` | Create a merge request |
| `get_pull_request_diffs` | Get merge request changes |
| `merge_pull_request` | Merge a merge request |
### CI/CD (Pipelines / Workflow Runs)
| Tool | Description |
| -------------------- | ---------------------------------------------- |
| `get_pipeline` | Get pipeline/workflow run status |
| `list_pipelines` | List pipelines/workflow runs |
| `list_pipeline_jobs` | List pipeline jobs/workflow jobs |
| `get_job_log` | Get job log output |
> Note: GitHub Actions workflow runs map to GitLab pipelines. The same tools work for both platforms.
### Comments
| Tool | Description |
| ---------------- | ----------------------- |
| `create_comment` | Add comment to issue/MR |
| `list_comments` | List comments |
### Users
| Tool | Description |
| -------- | ------------------------------ |
| `get_me` | Get current authenticated user |
## Configuration
| Environment Variable | Required | Default | Description |
| -------------------- | -------- | ---------------- | ------------------------------------------- |
| `GIT_PROVIDER` | No | `gitlab` | Provider type: `gitlab` or `github` |
| `GIT_TOKEN` | Yes | - | Personal Access Token |
| `GIT_API_URL` | No | Provider default | API URL (auto-detected from provider) |
| `GIT_AUTH_TYPE` | No | `bearer` | Auth type: `bearer` or `private-token` |
| `GIT_READ_ONLY` | No | `false` | Disable write operations |
| `LOG_LEVEL` | No | `info` | Log level: `debug`, `info`, `warn`, `error` |
## Architecture
```
src/
├── index.ts # Entry point
├── server.ts # MCP server (provider-agnostic)
├── config.ts # Configuration (multi-provider)
├── providers/ # Platform abstraction
│ ├── interface.ts # GitProvider interface
│ ├── types.ts # Platform-agnostic types
│ ├── config.ts # Provider configuration
│ ├── factory.ts # Provider Factory (creates GitLab/GitHub)
│ ├── gitlab/ # GitLab implementation
│ └── github/ # GitHub implementation
├── tools/ # Tool definitions
│ ├── define.ts # defineTool helper
│ ├── registry.ts # Tool registry
│ ├── repository/ # Repository tools
│ ├── issues/ # Issue tools
│ ├── merge-requests/ # PR/MR tools
│ ├── pipelines/ # CI/CD tools
│ ├── notes/ # Comment tools
│ └── users/ # User tools
├── gitlab/ # GitLab API client
│ ├── client.ts # HTTP client
│ └── types.ts # GitLab API types
├── github/ # GitHub API client
│ ├── client.ts # HTTP client
│ └── types.ts # GitHub API types
├── auth/ # Authentication
└── lib/ # Utilities
```
## Development
```bash
# Install dependencies
npm install
# Build
npm run build
# Run tests
npm test
# Run locally
npm start
# Development mode (watch)
npm run dev
```
## Adding a New Tool
1. Create file: `src/tools/{category}/{action}.ts`
```typescript
import { z } from 'zod';
import { defineTool, repoParam } from '../define.js';
const schema = z.object({
repo: repoParam,
// ... your params
});
export const myTool = defineTool({
name: 'my_tool',
description: 'What this tool does',
schema,
category: 'my-category',
read_only: true,
handler: async (input, ctx) => {
return ctx.provider.repository.someMethod(input.repo, ...);
},
});
```
2. Export from category index: `src/tools/{category}/index.ts`
3. Add to allTools: `src/tools/index.ts`
## Inspired By
- [gitlab-mcp](https://github.com/zereight/gitlab-mcp) - GitLab MCP server
- [github-mcp-server](https://github.com/github/github-mcp-server) - Official GitHub MCP server
## License
MIT
