gitlab-local-mcp

An MCP (Model Context Protocol) server for GitLab merge request workflows. Lets AI assistants list, create, review, and comment on merge requests. All tools that operate on a specific MR accept an optional merge_request_iid — omit it and the server auto-detects the open MR from the current git branch so you don't need to specify project or MR IDs.

Quick Start

npx gitlab-local-mcp

Or install globally:

npm install -g gitlab-local-mcp

Setup

git clone https://github.com/AlexShul/gitlab-local-mcp.git
cd gitlab-local-mcp
npm install

Environment Variables

| Variable | Required | Description | |---|---|---| | MR_MCP_GITLAB_TOKEN | Yes | GitLab personal access token (needs api scope) | | MR_MCP_GITLAB_HOST | Yes | GitLab instance URL (e.g. https://gitlab.com) | | MR_MCP_PROJECT_ID | No | Default project ID — used when project_id is omitted from tool calls | | MR_MCP_REPO_DIR | No | Path to your local git repo — enables auto-detection of the project ID and current-branch MR when IDs are omitted |

Copy .env.example to .env and fill in your values for local development.

Running

npm start

The server communicates over stdio, so it's designed to be launched by an MCP client rather than run standalone.

Client Configuration

This server works with any MCP-compatible client. Below are examples for popular clients.

Cursor

Add to your .cursor/mcp.json:

{
  "mcpServers": {
    "gitlab-local-mcp": {
      "command": "npx",
      "args": ["-y", "gitlab-local-mcp"],
      "env": {
        "MR_MCP_GITLAB_TOKEN": "glpat-xxxxxxxxxxxxxxxxxxxx",
        "MR_MCP_GITLAB_HOST": "https://gitlab.com",
        "MR_MCP_REPO_DIR": "/path/to/your/repo"
      }
    }
  }
}

Or if you cloned the repo locally:

{
  "mcpServers": {
    "gitlab-local-mcp": {
      "command": "node",
      "args": ["/path/to/gitlab-local-mcp/index.mjs"],
      "env": {
        "MR_MCP_GITLAB_TOKEN": "glpat-xxxxxxxxxxxxxxxxxxxx",
        "MR_MCP_GITLAB_HOST": "https://gitlab.com",
        "MR_MCP_REPO_DIR": "/path/to/your/repo"
      }
    }
  }
}

Other MCP Clients

Any client that supports the MCP stdio transport can launch this server. Point it at npx gitlab-local-mcp (or node /path/to/index.mjs) and pass the environment variables listed above.

Configuration Notes

MR_MCP_REPO_DIR is the recommended way to configure the server. It enables auto-detection of the project ID from the git remote URL and the current MR from the active branch, so MR_MCP_PROJECT_ID is no longer needed in most cases. You can still set MR_MCP_PROJECT_ID as a fallback for repos without a GitLab remote, or pass repo_dir / project_id / merge_request_iid per tool call instead of relying on environment variables.

Available Tools

Project Discovery

| Tool | Description | |---|---| | get_projects | Get projects visible to the current token. Useful for discovering project IDs. |

Merge Requests

All tools below accept optional project_id and repo_dir parameters. Tools that act on a specific MR also accept an optional merge_request_iid — when omitted, the server resolves the open MR whose source branch matches the current git branch (requires repo_dir or MR_MCP_REPO_DIR).

| Tool | Description | |---|---| | list_open_merge_requests | List merge requests for a project. Defaults to state=opened. Can filter by source_branch. | | create_merge_request | Create a new merge request. Omit source_branch to use the current git branch. | | get_merge_request_details | Get full details for a merge request. | | get_merge_request_diff | Get file-level diffs for a merge request. | | get_merge_request_comments | Get MR discussion notes. Returns unresolved notes only by default. | | add_merge_request_comment | Add a general (non-line-specific) comment to an MR. | | add_merge_request_diff_comment | Add a line-specific review comment on an MR diff. | | reply_to_merge_request_thread | Reply to an existing discussion thread in a merge request. | | resolve_merge_request_discussion | Resolve or unresolve a merge request discussion thread. | | approve_merge_request | Approve a merge request. | | merge_merge_request | Merge (accept) a merge request. Optionally squash commits or provide a custom merge commit message. |

Contributing

See CONTRIBUTING.md for development setup and guidelines.

License

MIT