Package Exports

This package does not declare an exports field, so the exports above have been automatically detected and optimized by JSPM instead. If any package subpath is missing, it is recommended to post an issue to the original package (@zereight/mcp-gitlab) to support the "exports" field. If that is not possible, create a JSPM override to customize the exports field for this package.

Readme

Better GitLab MCP Server

@zereight/mcp-gitlab

GitLab MCP(Model Context Protocol) Server. Includes bug fixes and improvements over the original GitLab MCP server.

Usage

Using with Claude App, Cline, Roo Code, Cursor

When using with the Claude App, you need to set up your API key and URLs directly.

npx

{
  "mcpServers": {
    "GitLab communication server": {
      "command": "npx",
      "args": ["-y", "@zereight/mcp-gitlab"],
      "env": {
        "GITLAB_PERSONAL_ACCESS_TOKEN": "your_gitlab_token",
        "GITLAB_API_URL": "your_gitlab_api_url",
        "GITLAB_READ_ONLY_MODE": "false",
        "USE_GITLAB_WIKI": "false", // use wiki api?
        "USE_MILESTONE": "false", // use milestone api?
        "USE_PIPELINE": "false" // use pipeline api?
      }
    }
  }
}

vscode .vscode/mcp.json

{
  "inputs": [
    {
      "type": "promptString",
      "id": "gitlab-token",
      "description": "Gitlab Token to read API",
      "password": true
    }
  ],
  "servers": {
    "GitLab-MCP": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "@zereight/mcp-gitlab"],
      "env": {
        "GITLAB_PERSONAL_ACCESS_TOKEN": "${input:gitlab-token}",
        "GITLAB_API_URL": "your-fancy-gitlab-url",
        "GITLAB_READ_ONLY_MODE": "true",
        ...
      }
    }
  }
}

Docker

stdio mcp.json

{
  "mcpServers": {
    "GitLab communication server": {
      "command": "docker",
      "args": [
        "run",
        "-i",
        "--rm",
        "-e",
        "GITLAB_PERSONAL_ACCESS_TOKEN",
        "-e",
        "GITLAB_API_URL",
        "-e",
        "GITLAB_READ_ONLY_MODE",
        "-e",
        "USE_GITLAB_WIKI",
        "-e",
        "USE_MILESTONE",
        "-e",
        "USE_PIPELINE",
        "iwakitakuma/gitlab-mcp"
      ],
      "env": {
        "GITLAB_PERSONAL_ACCESS_TOKEN": "your_gitlab_token",
        "GITLAB_API_URL": "https://gitlab.com/api/v4", // Optional, for self-hosted GitLab
        "GITLAB_READ_ONLY_MODE": "false",
        "USE_GITLAB_WIKI": "true",
        "USE_MILESTONE": "true",
        "USE_PIPELINE": "true"
      }
    }
  }
}

docker run -i --rm \
  -e GITLAB_PERSONAL_ACCESS_TOKEN=your_gitlab_token \
  -e GITLAB_API_URL= "https://gitlab.com/api/v4"\
  -e GITLAB_READ_ONLY_MODE=true \
  -e USE_GITLAB_WIKI=true \
  -e USE_MILESTONE=true \
  -e USE_PIPELINE=true \
  -e SSE=true \
  -p 3333:3002 \
  iwakitakuma/gitlab-mcp

{
  "mcpServers": {
    "GitLab communication server": {
      "type": "sse",
      "url": "http://localhost:3333/sse"
    }
  }
}

Docker Image Push

$ sh scripts/image_push.sh docker_user_name

Environment Variables

GITLAB_PERSONAL_ACCESS_TOKEN: Your GitLab personal access token.
GITLAB_API_URL: Your GitLab API URL. (Default: https://gitlab.com/api/v4)
GITLAB_PROJECT_ID: Default project ID. If set, Overwrite this value when making an API request.
GITLAB_READ_ONLY_MODE: When set to 'true', restricts the server to only expose read-only operations. Useful for enhanced security or when write access is not needed. Also useful for using with Cursor and it's 40 tool limit.
USE_GITLAB_WIKI: When set to 'true', enables the wiki-related tools (list_wiki_pages, get_wiki_page, create_wiki_page, update_wiki_page, delete_wiki_page). By default, wiki features are disabled.
USE_MILESTONE: When set to 'true', enables the milestone-related tools (list_milestones, get_milestone, create_milestone, edit_milestone, delete_milestone, get_milestone_issue, get_milestone_merge_requests, promote_milestone, get_milestone_burndown_events). By default, milestone features are disabled.
USE_PIPELINE: When set to 'true', enables the pipeline-related tools (list_pipelines, get_pipeline, list_pipeline_jobs, get_pipeline_job, get_pipeline_job_output, create_pipeline, retry_pipeline, cancel_pipeline). By default, pipeline features are disabled.
GITLAB_AUTH_COOKIE_PATH: Path to an authentication cookie file for GitLab instances that require cookie-based authentication. When provided, the cookie will be included in all GitLab API requests.

Tools 🛠️

create_or_update_file - Create or update a single file in a GitLab project
search_repositories - Search for GitLab projects
create_repository - Create a new GitLab project
get_file_contents - Get the contents of a file or directory from a GitLab project
push_files - Push multiple files to a GitLab project in a single commit
create_issue - Create a new issue in a GitLab project
create_merge_request - Create a new merge request in a GitLab project
fork_repository - Fork a GitLab project to your account or specified namespace
create_branch - Create a new branch in a GitLab project
get_merge_request - Get details of a merge request (Either mergeRequestIid or branchName must be provided)
get_merge_request_diffs - Get the changes/diffs of a merge request (Either mergeRequestIid or branchName must be provided)
list_merge_request_diffs - List merge request diffs with pagination support (Either mergeRequestIid or branchName must be provided)
get_branch_diffs - Get the changes/diffs between two branches or commits in a GitLab project
update_merge_request - Update a merge request (Either mergeRequestIid or branchName must be provided)
create_note - Create a new note (comment) to an issue or merge request
create_merge_request_thread - Create a new thread on a merge request
mr_discussions - List discussion items for a merge request
update_merge_request_note - Modify an existing merge request thread note
create_merge_request_note - Add a new note to an existing merge request thread
update_issue_note - Modify an existing issue thread note
create_issue_note - Add a new note to an existing issue thread
list_issues - List issues in a GitLab project with filtering options
get_issue - Get details of a specific issue in a GitLab project
update_issue - Update an issue in a GitLab project
delete_issue - Delete an issue from a GitLab project
list_issue_links - List all issue links for a specific issue
list_issue_discussions - List discussions for an issue in a GitLab project
get_issue_link - Get a specific issue link
create_issue_link - Create an issue link between two issues
delete_issue_link - Delete an issue link
list_namespaces - List all namespaces available to the current user
get_namespace - Get details of a namespace by ID or path
verify_namespace - Verify if a namespace path exists
get_project - Get details of a specific project
list_projects - List projects accessible by the current user
list_labels - List labels for a project
get_label - Get a single label from a project
create_label - Create a new label in a project
update_label - Update an existing label in a project
delete_label - Delete a label from a project
list_group_projects - List projects in a GitLab group with filtering options
list_wiki_pages - List wiki pages in a GitLab project
get_wiki_page - Get details of a specific wiki page
create_wiki_page - Create a new wiki page in a GitLab project
update_wiki_page - Update an existing wiki page in a GitLab project
delete_wiki_page - Delete a wiki page from a GitLab project
get_repository_tree - Get the repository tree for a GitLab project (list files and directories)
list_pipelines - List pipelines in a GitLab project with filtering options
get_pipeline - Get details of a specific pipeline in a GitLab project
list_pipeline_jobs - List all jobs in a specific pipeline
get_pipeline_job - Get details of a GitLab pipeline job number
get_pipeline_job_output - Get the output/trace of a GitLab pipeline job number
create_pipeline - Create a new pipeline for a branch or tag
retry_pipeline - Retry a failed or canceled pipeline
cancel_pipeline - Cancel a running pipeline
list_merge_requests - List merge requests in a GitLab project with filtering options
list_milestones - List milestones in a GitLab project with filtering options
get_milestone - Get details of a specific milestone
create_milestone - Create a new milestone in a GitLab project
edit_milestone - Edit an existing milestone in a GitLab project
delete_milestone - Delete a milestone from a GitLab project
get_milestone_issue - Get issues associated with a specific milestone
get_milestone_merge_requests - Get merge requests associated with a specific milestone
promote_milestone - Promote a milestone to the next stage
get_milestone_burndown_events - Get burndown events for a specific milestone
get_users - Get GitLab user details by usernames