git-mcp-server

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

{
  "mcpServers": {
    "git": {
      "command": "npx",
      "args": ["-y", "@raytien/git-mcp-server"],
      "env": {
        "GIT_PROVIDER": "github",
        "GIT_TOKEN": "ghp_xxxxxxxxxxxxxxxxxxxx"
      }
    }
  }
}

GitHub Enterprise

{
  "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)

{
  "mcpServers": {
    "git": {
      "command": "npx",
      "args": ["-y", "@raytien/git-mcp-server"],
      "env": {
        "GIT_PROVIDER": "gitlab",
        "GIT_TOKEN": "glpat-xxxxxxxxxxxxxxxxxxxx"
      }
    }
  }
}

Self-Hosted GitLab

{
  "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

{
  "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

# 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

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, ...);
    },
});

1. Export from category index: src/tools/{category}/index.ts
2. Add to allTools: src/tools/index.ts

Inspired By

• gitlab-mcp - GitLab MCP server
• github-mcp-server - Official GitHub MCP server

License

MIT