GitLab MCP Server

MCP (Model Context Protocol) server để tích hợp với GitLab API, cho phép AI assistants tương tác với GitLab thông qua các tools và resources.

Tính năng

Tools (Các thao tác có thể thực hiện)

Project Tools

• list_projects - Liệt kê GitLab projects
• get_project - Lấy thông tin chi tiết project
• create_project - Tạo project mới
• search_projects - Tìm kiếm projects

Issue Tools

• list_issues - Liệt kê issues
• get_issue - Lấy thông tin chi tiết issue
• create_issue - Tạo issue mới
• update_issue - Cập nhật issue
• close_issue - Đóng issue

Merge Request Tools

• list_merge_requests - Liệt kê merge requests
• get_merge_request - Lấy thông tin chi tiết merge request
• create_merge_request - Tạo merge request mới
• update_merge_request - Cập nhật merge request
• merge_merge_request - Merge merge request

File Tools

• get_file - Đọc file từ repository
• list_files - Liệt kê files trong directory
• create_file - Tạo file mới
• update_file - Cập nhật file

Resources (Dữ liệu có thể truy cập)

• gitlab://projects - Danh sách projects
• gitlab://issues - Danh sách issues
• gitlab://merge-requests - Danh sách merge requests
• gitlab://project/{projectId} - Thông tin project cụ thể
• gitlab://issue/{projectId}/{issueIid} - Thông tin issue cụ thể
• gitlab://merge-request/{projectId}/{mrIid} - Thông tin merge request cụ thể
• gitlab://file/{projectId}/{filePath} - Nội dung file

Cài đặt

Yêu cầu

• Node.js >= 18.0.0
• GitLab Personal Access Token với các quyền: api, read_api, write_repository

Cài đặt dependencies

npm install

Cài đặt global (tùy chọn)

Để cài đặt package này như một global command, bạn có thể sử dụng:

npm run install-global

Hoặc cài đặt trực tiếp từ thư mục hiện tại:

npm run build
npm install -g .

Sau khi cài đặt global, bạn có thể chạy server từ bất kỳ đâu bằng lệnh:

gitlab-mcp-server

Sử dụng với npx (không cần cài đặt)

Bạn cũng có thể chạy trực tiếp bằng npx mà không cần cài đặt global:

npx -y gitlab-mcp-server

Lưu ý: Nếu package chưa được publish lên npm, bạn có thể sử dụng npx với đường dẫn local:

npx -y /path/to/mcp_ts

Cấu hình

1. Copy file env.example thành .env:

cp env.example .env

2. Chỉnh sửa file .env và thêm GitLab token của bạn:

GITLAB_TOKEN=your_gitlab_personal_access_token_here
GITLAB_URL=https://gitlab.com/api/v4

Đối với GitLab self-hosted, thay đổi GITLAB_URL thành URL của instance của bạn.

Sử dụng

Build project

npm run build

Chạy server

npm start

Hoặc chạy ở chế độ development với auto-reload:

npm run dev

Type checking

npm run type-check

Cấu hình MCP Client

Claude Desktop

Thêm cấu hình sau vào file MCP settings của Claude Desktop (thường ở ~/Library/Application Support/Claude/claude_desktop_config.json trên macOS hoặc %APPDATA%\Claude\claude_desktop_config.json trên Windows):

Tùy chọn 1: Sử dụng npx (khuyến nghị, không cần cài đặt global):

{
  "mcpServers": {
    "gitlab": {
      "command": "npx",
      "args": ["-y", "gitlab-mcp-server"],
      "env": {
        "GITLAB_TOKEN": "your_gitlab_token_here",
        "GITLAB_URL": "https://gitlab.com/api/v4"
      }
    }
  }
}

Tùy chọn 2: Nếu đã cài đặt global:

{
  "mcpServers": {
    "gitlab": {
      "command": "gitlab-mcp-server",
      "env": {
        "GITLAB_TOKEN": "your_gitlab_token_here",
        "GITLAB_URL": "https://gitlab.com/api/v4"
      }
    }
  }
}

Tùy chọn 3: Sử dụng đường dẫn local:

{
  "mcpServers": {
    "gitlab": {
      "command": "node",
      "args": ["/path/to/mcp_ts/dist/index.js"],
      "env": {
        "GITLAB_TOKEN": "your_gitlab_token_here",
        "GITLAB_URL": "https://gitlab.com/api/v4"
      }
    }
  }
}

Cursor IDE

Thêm cấu hình vào file MCP settings của Cursor:

Tùy chọn 1: Sử dụng npx (khuyến nghị, không cần cài đặt global):

{
  "mcpServers": {
    "gitlab": {
      "command": "npx",
      "args": ["-y", "gitlab-mcp-server"],
      "env": {
        "GITLAB_TOKEN": "your_gitlab_token_here",
        "GITLAB_URL": "https://gitlab.com/api/v4"
      }
    }
  }
}

Tùy chọn 2: Nếu đã cài đặt global:

{
  "mcpServers": {
    "gitlab": {
      "command": "gitlab-mcp-server",
      "env": {
        "GITLAB_TOKEN": "your_gitlab_token_here",
        "GITLAB_URL": "https://gitlab.com/api/v4"
      }
    }
  }
}

Tùy chọn 3: Sử dụng đường dẫn local:

{
  "mcpServers": {
    "gitlab": {
      "command": "node",
      "args": ["/path/to/mcp_ts/dist/index.js"],
      "env": {
        "GITLAB_TOKEN": "your_gitlab_token_here",
        "GITLAB_URL": "https://gitlab.com/api/v4"
      }
    }
  }
}

Ví dụ sử dụng

Liệt kê projects

{
  "tool": "list_projects",
  "arguments": {
    "search": "my-project",
    "owned": true
  }
}

Tạo issue

{
  "tool": "create_issue",
  "arguments": {
    "projectId": "123",
    "title": "Bug fix needed",
    "description": "This is a bug that needs to be fixed",
    "labels": "bug,urgent"
  }
}

Đọc file từ repository

{
  "tool": "get_file",
  "arguments": {
    "projectId": "group/project",
    "filePath": "src/index.ts",
    "ref": "main"
  }
}

Cấu trúc dự án

mcp_ts/
├── src/
│   ├── index.ts              # Entry point, MCP server setup
│   ├── config.ts             # Configuration management
│   ├── gitlab/
│   │   ├── client.ts         # GitLab API client wrapper
│   │   ├── projects.ts       # Project operations
│   │   ├── issues.ts         # Issue operations
│   │   ├── mergeRequests.ts  # MR operations
│   │   └── files.ts          # File operations
│   └── tools/
│       ├── projectTools.ts   # MCP tools for projects
│       ├── issueTools.ts     # MCP tools for issues
│       ├── mrTools.ts        # MCP tools for merge requests
│       └── fileTools.ts      # MCP tools for files
├── package.json
├── tsconfig.json
├── env.example
└── README.md

Phát triển

Thêm tool mới

1. Tạo function trong module tương ứng trong src/gitlab/
2. Thêm tool definition vào file tương ứng trong src/tools/
3. Thêm handler trong function handle*Tool tương ứng
4. Tool sẽ tự động được đăng ký trong MCP server

Error Handling

Tất cả các GitLab API calls đều được wrap với error handling. Errors sẽ được chuyển đổi thành messages dễ hiểu và trả về cho client.

License

MIT