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

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

Related MCP server: GitLab MCP Server

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

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.