gitlab-mcp-server

What is GitLab MCP Server?

A Model Context Protocol (MCP) server that allows AI assistants (like Claude) to interact with GitLab repositories. It provides comprehensive capabilities for managing projects, issues, merge requests, comments, labels, milestones, time tracking, and more. This enhanced implementation includes additional endpoints and improved error handling compared to the original MCP GitLab server.

How to use GitLab MCP Server?

Install globally (npm install -g @piatra-open-source/gitlab-mcp-server) or as a project dependency. Set the required environment variable GITLAB_PERSONAL_ACCESS_TOKEN (and optionally GITLAB_API_URL for self-managed instances). Run the server with gitlab-mcp-server or embed it in your application using the Node.js child process API.

Key features of GitLab MCP Server

• Project creation, update, deletion, forking, and search
• File operations: fetch, create/update, commit multiple files
• Issue management with filtering and time tracking
• Full CRUD for issue comments
• Label management: create, update, delete, attach/detach
• Milestone retrieval and creation
• User assignment and unassignment on issues
• Issue linking (relates_to, etc.) and link deletion

Use cases of GitLab MCP Server

• Create a project in a specific GitLab group with custom visibility
• Retrieve open issues with time tracking statistics
• Add spent time to an issue and update its attributes
• Manage comments (create, update, delete) on issues
• Create and assign labels and milestones to issues
• Link, unlink, and manage relationships between issues
• Automate repository administration (fork, delete, change visibility)

FAQ from GitLab MCP Server

What distinguishes this server from the original MCP GitLab server?

It adds comprehensive endpoints for delete/update projects, time tracking, notes, labels, milestones, user assignment, and issue linking, with fixed namespace_id handling and enhanced error messages.

What environment variables are required?

GITLAB_PERSONAL_ACCESS_TOKEN (mandatory) and GITLAB_API_URL (optional, defaults to https://gitlab.com/api/v4).

Why do I get a “file_path should be a valid file path” error?

GitLab expects properly formatted paths (forward slashes, no invalid characters, case-sensitive). Ensure the file path exists in the repository for updates and avoid special characters like #, ?, [, ].

How do I handle authentication or permission issues?

Verify your personal access token has the necessary scopes. Check you have adequate access rights to the repository and group. Be aware of GitLab API rate limits.

Does the server support self-managed GitLab instances?

Yes, by setting the GITLAB_API_URL environment variable to your custom GitLab API endpoint.