The GitLab MCP server, enumerated live on a real Mac.

• Tools

  116, enumerated live

• Credentials

  GitLab personal access token [5][10]

• Transport

  stdio, runs on your Mac [1][4]

• Maintainer

  zereight, community [1][3]

• Downloads

  114,673 last week [2]

• License

  MIT [1][3]

Verification

How this MCP server was verified.

Method

We spawned the server with npx over stdio with two environment variables and nothing else: GITLAB_PERSONAL_ACCESS_TOKEN holding a dummy glpat-style placeholder rather than a real token, and GITLAB_API_URL set to https://gitlab.com/api/v4, which the server logged straight back to us as the API URL it had configured. It completed the MCP initialize handshake, introduced itself as zereight-gitlab-mcp-server 2.1.46 on protocol 2025-06-18, and answered tools/list with all 116 tools, and the table below is that answer, word for word. Before any of it, the server printed the two notices quoted as the startup banner, which every start of this version prints because two branch tools belong to two toolsets at once. That run made no tool call. Four more runs of the same command followed on the same Mac within two minutes. In the first we called whoami, the tool that asks GitLab who the token belongs to, and GitLab answered 401 Unauthorized after 294 milliseconds: the call left the Mac and was refused at the other end, because a placeholder is not a token, and that reply is the sample call below. In the second we called health_check, which came back as an ordinary reply whose payload reported authentication false. In the third we sent search_repositories a number where it expects text, and the server refused it in 6 milliseconds without contacting GitLab. The fourth was started with no token in the environment at all, and stopped instead of starting. The tools are therefore enumerated live and every error on this page is real output, while a successful authenticated call still waits for a GitLab personal access token you create yourself.

Tool "get_branch" is defined in multiple toolsets: "merge_requests" and "branches"
Tool "list_branches" is defined in multiple toolsets: "merge_requests" and "branches"

tools/call whoami {}

GitLab API error: 401 Unauthorized
{"message":"401 Unauthorized"}

Real lines from the captured result: enough to prove the call answered.

Tools

Every tool, enumerated from the running server.

The server answered tools/list with 116 tools on 2026-08-03. The names, descriptions and parameters below are its own words, copied from that response and never edited.

Parameters marked with * are required.

Setup

Working configs, one per app.

Copy the block for the app you use. Each one is the configuration this server was verified with.

{
  "mcpServers": {
    "gitlab": {
      "command": "npx",
      "args": [
        "-y",
        "@zereight/mcp-gitlab"
      ],
      "env": {
        "GITLAB_PERSONAL_ACCESS_TOKEN": "glpat-your-token",
        "GITLAB_API_URL": "https://gitlab.com/api/v4"
      }
    }
  }
}

claude mcp add gitlab --transport stdio --scope local \
  --env GITLAB_PERSONAL_ACCESS_TOKEN=glpat-your-token \
  --env GITLAB_API_URL=https://gitlab.com/api/v4 \
  -- npx -y @zereight/mcp-gitlab

{
  "mcpServers": {
    "gitlab": {
      "command": "npx",
      "args": [
        "-y",
        "@zereight/mcp-gitlab"
      ],
      "env": {
        "GITLAB_PERSONAL_ACCESS_TOKEN": "glpat-your-token",
        "GITLAB_API_URL": "https://gitlab.com/api/v4",
        "GITLAB_READ_ONLY_MODE": "false"
      }
    }
  }
}

Name        GitLab
Command     npx
Arguments   -y @zereight/mcp-gitlab

Environment Variables
GITLAB_PERSONAL_ACCESS_TOKEN    glpat-your-token
GITLAB_API_URL                  https://gitlab.com/api/v4

No terminal needed

Set the GitLab MCP server up without the terminal.

If you have never opened Terminal and never want to, this is your path. Routines is a Mac app that runs MCP servers for you: fill in a few fields once, and this server's tools are available to your AI in chat and in scheduled routines. Unlike a file server, this one needs a token from GitLab first, so that is step two.

1. 01

   Install Routines

   Download the app from getroutines.ai/download, drag it to Applications, and sign in.

2. 02

   Create a GitLab access token

   In GitLab, select your avatar in the upper-right corner, then Edit profile, then Access and Personal access tokens in the left sidebar, then Generate token. Give it a name and an expiry date you are comfortable with, and pick a scope: api grants complete read and write access to the API, read_api grants read access only, which is the one to start with if you want the assistant to look and not touch. GitLab shows the token once, so copy it before you close the page.

3. 03

   Open the MCP settings

   Click your account at the bottom of the sidebar and choose Settings. Open the Assistant section, then the Connections tab, scroll to MCP Servers, and click Add MCP Server.

4. 04

   Choose Command (stdio)

   Switch the form to Command (stdio): this server is a command your Mac runs, not a web address. Name: GitLab. Command: npx. Arguments: -y @zereight/mcp-gitlab, exactly those three words.

5. 05

   Add the token and say which GitLab

   In Environment Variables add GITLAB_PERSONAL_ACCESS_TOKEN with the token you copied. Add a second one, GITLAB_API_URL, set to https://gitlab.com/api/v4 for the public service, or to your company instance with /api/v4 on the end. This step is not optional: with that first variable empty the server stops instead of starting, which we saw for ourselves.

6. 06

   Test, add, and use it

   Click Test Connection: Routines starts the server and reports how many tools it found, one hundred and sixteen for this one. Then click Add Server. Ask a read-only question first, such as who you are signed in to GitLab as, because that is what proves the token itself works. To let a scheduled routine use these tools, open the routine, find the Tools & connections card, and tick the server under Apps.

Routine ideas

Routines worth scheduling.

Once the server is connected, a scheduled routine can use its tools while you are away. Copy a prompt, paste it into Routines, and pick a time.

Troubleshooting

The errors we hit, and what fixed them.

Real errors captured during the verification run, printed exactly as the server returned them.

GITLAB_PERSONAL_ACCESS_TOKEN environment variable is not set
Either set GITLAB_PERSONAL_ACCESS_TOKEN or enable OAuth with GITLAB_USE_OAUTH=true

GitLab API error: 401 Unauthorized
{"message":"401 Unauthorized"}

Invalid arguments: search: Expected string, received number

Tool "get_branch" is defined in multiple toolsets: "merge_requests" and "branches"
Tool "list_branches" is defined in multiple toolsets: "merge_requests" and "branches"

FAQ

Questions people ask.

Sources

Every external claim, receipted.

Anything on this page we did not observe in the run is linked here, with the date we read it. The run itself is the receipt for the rest.

1. [1]

   npm registry: @zereight/mcp-gitlabaccessed 2026-08-03

   Latest version 2.1.46, published 2026-08-02 by GitHub Actions CI; license MIT; maintainer zereight; keywords include stdio, sse and streamable-http; binaries mcp-gitlab and zereight-mcp-gitlab.

2. [2]

   npm downloads API: last weekaccessed 2026-08-03

   114,673 downloads for the week 2026-07-27 to 2026-08-02, against 5,632 for @modelcontextprotocol/server-gitlab in the same week.

3. [3]

   GitHub: zereight/gitlab-mcpaccessed 2026-08-03

   1,870 stars, license MIT, archived false, last push 2026-08-03, owner type User, read from the GitHub REST API.

4. [4]

   GitLab MCP Server READMEaccessed 2026-08-03

   Source for the recommended zereight-mcp-gitlab binary name over the older mcp-gitlab, and for the stdio, SSE and Streamable HTTP transport options.

5. [5]

   GitLab MCP Server docs: environment variablesaccessed 2026-08-03

   GITLAB_PERSONAL_ACCESS_TOKEN, GITLAB_API_URL pointing at the API root ending in /api/v4, and GITLAB_READ_ONLY_MODE=true to restrict the server to read-only tools.

6. [6]

   GitLab MCP Server docs: Claude Code setup guideaccessed 2026-08-03

   The claude mcp add command with --transport stdio, --scope local and the two --env values.

7. [7]

   GitLab MCP Server docs: Cursor setup guideaccessed 2026-08-03

   The .cursor/mcp.json block, plus the guide's own note that it is a best-effort community pattern rather than repository-verified official Cursor documentation.

8. [8]

   npm registry: @modelcontextprotocol/server-gitlabaccessed 2026-08-03

   The retired official reference server: latest version 2025.4.25, carrying the npm notice "Package no longer supported. Contact Support at https://www.npmjs.com/support for more info."

9. [9]

   GitHub: modelcontextprotocol/servers-archivedaccessed 2026-08-03

   archived true, described as "Reference MCP servers that are no longer maintained", last push 2025-05-28, read from the GitHub REST API.

10. [10]

    GitLab docs: Personal access tokensaccessed 2026-08-03

    The creation path quoted in the walkthrough: avatar, Edit profile, then Access and Personal access tokens in the left sidebar, then Generate token.

11. [11]

    GitLab docs: Access token scopesaccessed 2026-08-03

    api "Grants complete read and write access to the API for the token's scope"; read_api "Grants read access to the API for the token's scope".

12. [12]

    modelcontextprotocol.io: Connect to local MCP serversaccessed 2026-08-03

    The claude_desktop_config.json shape and where the file lives.

13. [13]

    Claude Code docs: MCPaccessed 2026-08-03

    The claude mcp add syntax for local stdio servers, including --env and --scope.

14. [14]

    Cursor docs: Model Context Protocolaccessed 2026-08-03

    The mcp.json shape and file locations.

15. [15]

    Routines: Connectorsaccessed 2026-08-03

    How Routines runs one-click OAuth connectors and any MCP server.

This page describes GitLab as it behaved in one dated run on one Mac. Versions move: if something here no longer matches what you see, the capture date at the top says how old the reading is.