mcp-gitlab

This MCP server provides a comprehensive GitLab integration with a wide range of tools that enable AI-assisted development workflows. It exposes a standardized set of MCP endpoints to manage repositories, files, branches, issues, merge requests, CI/CD pipelines, wikis, members, groups, labels, milestones, releases, and more. The server supports both stdio and Server-Sent Events (SSE) transports, allowing flexible integration with chatbots, IDEs, and automation pipelines. To use it, configure the MCP client to point at the gitlab server and supply the required environment variables, notably your GitLab Personal Access Token and the GitLab instance URL. Once connected, you can issue natural-language commands or structured tool calls to perform complex GitLab operations through AI, such as creating an MR with auto-generated descriptions, triggering pipelines, or updating project settings. The server also supports read-only mode for safe exploration without write permissions, helping to prototype AI-assisted workflows before enabling write access.

Prerequisites:

• Node.js and npm installed on the machine
• Access to the internet to fetch the MCP server package
• Git installed if you plan to clone the repository

Option A: Install from npm (recommended)

1. Install the MCP server package:

npm install @yoda.digital/gitlab-mcp-server

2. Run the server directly with npx (no local install required):

# Example (from Claude Desktop configuration):
npx -y @yoda.digital/gitlab-mcp-server

Option B: Install from source

1. Clone the repository:

git clone https://github.com/yoda-digital/mcp-gitlab-server.git
cd mcp-gitlab-server

2. Install dependencies:

npm install

3. Build if your workflow requires a built dist:

npm run build

4. Run the server (pointing to the built entry if applicable):

node_modules/.bin/<start-script-if-present>  # or npm run start

Configuration:

• Create or update your Claude Desktop config (or equivalent MCP client) to include the server with the following structure:

{
  "mcpServers": {
    "gitlab": {
      "command": "npx",
      "args": ["-y", "@yoda.digital/gitlab-mcp-server"],
      "env": {
        "GITLAB_PERSONAL_ACCESS_TOKEN": "your-token-here",
        "GITLAB_URL": "https://gitlab.com",
        "GITLAB_READ_ONLY": "false"
      }
    }
  }
}

Notes:

• Ensure your GitLab PAT has the necessary scopes for the tools you plan to use.
• If you installed from source or prefer running locally, you can point to the built server entrypoint as described in the README.

Environment variables:

• GITLAB_PERSONAL_ACCESS_TOKEN: Required; your GitLab PAT with appropriate scopes.
• GITLAB_URL: GitLab instance URL (default: https://gitlab.com).
• GITLAB_READ_ONLY: Set to true to enable read-only mode (optional). Common issues:
• If tokens are rejected, verify token scopes and that the GITLAB_URL matches your instance.
• When using npx, ensure network access is available to fetch the package; behind a proxy may require configuration.
• For non-npx deployments, ensure the path to the local dist/index.js (or equivalent) is correctly provided in the client configuration.
• Review logs for transport issues (stdio vs SSE) and adjust your client to match the server transport being used.