gitlab

This MCP server provides a fully typed interface to GitLab via the Model Context Protocol (MCP). It exposes a suite of tools to manage common GitLab workflows through Claude: projects, issues, merge requests, pipelines, jobs, repository information, and user details. You can list projects, fetch issue lists, create and update merge requests with complete review workflows (including comments, discussions, and inline code comments), manage pipelines and jobs (with access to logs and advanced trace options), and inspect repository data like branches and commits. The server is TypeScript-typed, ensuring strong type safety when interacting with GitLab resources, and supports both standard and self-hosted GitLab instances via a configurable base URL. Typical usage involves asking Claude to perform targeted actions such as listing projects, creating an MR from one branch to another, or fetching MR comments for a given project.

Prerequisites:

• Node.js and npm (or npx comes with npm)
• A GitLab Personal Access Token with api, read_user, and read_repository scopes
• Optional: access to a self-hosted GitLab instance if you are not using gitlab.com

Install and configure:

1. Ensure Node.js and npm are installed. Verify with: node -v npm -v

2. Prepare your GitLab MCP server configuration for Claude Desktop (or your environment):

   • Use the commands below to configure the server entry which uses npx to run the MCP server package.

3. Obtain a GitLab token:

   • Create a Personal Access Token in GitLab with the following scopes: api, read_user, read_repository

4. Add the MCP server configuration to Claude Desktop (example shown in repository):

   • In Claude Desktop config file (e.g., ~/Library/Application Support/Claude/claude_desktop_config.json on macOS):

     { "mcpServers": { "gitlab": { "command": "npx", "args": ["-y", "@alosies/gitlab-mcp-server"], "env": { "NPM_CONFIG_TOKEN": "your-gitlab-token-here" } } } }

5. Start using the MCP server via Claude by asking natural language questions like:

   • "List my GitLab projects"
   • "Show open issues in myproject"
   • "Create a merge request from feature-branch to main"

Note: If you are using a self-hosted GitLab instance, set GITLAB_BASE_URL in the env:

• GITLAB_BASE_URL: https://gitlab.mycompany.com

6. Optional: you can adjust additional configuration options as described in the documentation (docs/configuration.md).

Tips and known considerations:

• The MCP server relies on a GitLab token; keep it secure and rotate as needed. Do not expose your token in logs.
• If using a self-hosted GitLab instance, set GITLAB_BASE_URL to the appropriate base URL in your environment.
• When creating complex workflows (e.g., MR with templates, discussions, and reviewer filters), refer to the Tools and Usage docs for parameter details and supported commands.
• If you encounter authentication issues, verify token scopes and that the token is active for the user making requests.
• For self-hosted setups, ensure network accessibility from the MCP server to your GitLab instance (firewalls, proxies, and TLS considerations).
• The server is TypeScript-typed; use the available types to catch mismatched parameters early in CLI interactions.
• If you need to run locally without Claude, you can adapt the same npx command and environment variables in your local terminal for testing.