gitlab-mcp-server

An MCP (Model Context Protocol) server for a self-hosted GitLab instance, focused on browsing projects and repositories. It exposes read-only tools so an MCP client (Claude desktop, Claude Code, etc.) can list projects, inspect branches and commits, browse the file tree, and read file contents.

Tools

Tool	Purpose
gitlab_list_projects	List / search projects, filter by owned or membership
gitlab_get_project	Detailed info for one project (default branch, clone URLs, etc.)
gitlab_list_branches	List repository branches with their tip commit
gitlab_list_commits	List commits, filter by ref / path / date range
gitlab_get_commit	Full details and line-change stats for one commit
gitlab_list_repository_tree	Browse files & directories at a path (optionally recursive)
gitlab_get_file	Read decoded contents of a single file

All tools are read-only and support pagination (page, per_page) and a response_format of markdown (default) or json.

Requirements

• Node.js 18+
• A GitLab Personal Access Token (PAT)

Setup

npm install
npm run build

Create a Personal Access Token

In GitLab: User Settings → Access Tokens. Create a token with these scopes:

• read_api — required for listing projects, branches and commits
• read_repository — required for the repository tree and file contents

Keep the token secret. It is read from an environment variable, never stored in code.

Configuration

Variable	Required	Description
GITLAB_BASE_URL	yes	Base URL of your instance, e.g. https://gitlab.example.com (no /api/v4 suffix needed)
GITLAB_TOKEN	yes	Your Personal Access Token
TRANSPORT	no	stdio (default) or http
PORT	no	Port for http transport (default 3000)

Running

# stdio (default — for local MCP clients)
GITLAB_BASE_URL=https://gitlab.example.com GITLAB_TOKEN=glpat-xxxx npm start

# HTTP transport (binds to 127.0.0.1)
TRANSPORT=http PORT=3000 GITLAB_BASE_URL=https://gitlab.example.com GITLAB_TOKEN=glpat-xxxx npm start

Connecting to an MCP client

Most desktop clients use a JSON config block. Point it at the built entry point and supply the environment variables:

{
  "mcpServers": {
    "gitlab": {
      "command": "node",
      "args": ["/absolute/path/to/gitlab-mcp-server/dist/index.js"],
      "env": {
        "GITLAB_BASE_URL": "https://gitlab.example.com",
        "GITLAB_TOKEN": "glpat-xxxxxxxxxxxxxxxxxxxx"
      }
    }
  }
}

Replace the path with the absolute path to dist/index.js on your machine, and fill in your instance URL and token. Restart the client to pick up the new server.

Project structure

gitlab-mcp-server/
├── package.json
├── tsconfig.json
├── README.md
└── src/
    ├── index.ts            # Entry point, transport selection, env validation
    ├── constants.ts        # Config readers and limits
    ├── types.ts            # GitLab resource interfaces
    ├── schemas/common.ts   # Shared Zod schema fragments
    ├── services/client.ts  # Authenticated API client, pagination, errors
    └── tools/projects.ts   # Tool definitions and registration

Identifying projects

Wherever a project_id is required, you can pass either:

• the numeric project ID, e.g. 42, or
• the namespace path, e.g. mygroup/myrepo (the server URL-encodes it for you).

Notes

• This server only performs read operations. It never creates, edits, or deletes anything in GitLab.
• Large file or list responses are truncated at 25,000 characters; use pagination or narrower filters to retrieve more.
• For development with auto-reload: npm run dev.