mcp-gitlab

The mcp-gitlab-server provides a GitLab integration for MCP clients by leveraging the python-gitlab library. It exposes a set of management and code-access capabilities that let you list and inspect projects and groups, read repository contents, and analyze merge requests. You can authenticate with either a GitLab personal access token or an OAuth2 token. Once configured, you can query the server to enumerate your GitLab resources, fetch repository details, read code, and retrieve merge request analytics such as lifetimes and metadata. This makes it suitable for automated workflows, dashboards, or tooling that needs programmatic GitLab access through a common MCP interface. The server is designed to work with both GitLab.com and self-hosted GitLab installations by configuring the GITLAB_URL environment variable accordingly.

Available tools include: list_projects, list_groups, list_group_projects, get_user_info, search_repositories, get_repository_details, read_repository_code, read_repository_file, list_merge_requests, and get_merge_request_analytics. Each command accepts common filters (e.g., project/group names, ownership, pagination, and branch/ref selection) and returns structured results suitable for downstream processing. The code-reading features support selective file inclusion/exclusion, size limits, and branch or tag references, while the merge request analytics offer timing statistics and percentile distributions to help evaluate development throughput.

Prerequisites:\n- Python environment compatible with uvx usage (as described in the repository, typically Python 3.x).\n- MCP client tooling installed to provision and run MCP servers.\n- Access token or OAuth2 token with at least read_api scope on your GitLab instance.\n- (Optional) Node.js or other runtime only if you plan to use a different deployment method; this server is configured for uvx/uv usage in the README.\n\nInstall steps:\n1) Install the MCP tooling if you haven’t already (follow your environment’s typical MCP installation method).\n2) Prepare your authentication credentials: either a GitLab personal access token or an OAuth2 token, and determine your GitLab URL (default to https://gitlab.com if not self-hosted).\n3) Create or edit your MCP configuration to point to the gitlab-mcp-server, using uvx as the command and providing the appropriate environment variables. Example configuration:\n\njson\n{\n "mcpServers": {\n "GitLab": {\n "command": "uvx",\n "args": [\n "gitlab-mcp-server"\n ],\n "env": {\n "GITLAB_TOKEN": "<your GitLab personal access token>",\n "GITLAB_URL": "https://gitlab.com"\n }\n }\n }\n}\n\n\n4) If you are using a wheel/local build for testing (as described in the Development/testing section), you can build and point to a local wheel instead:\n\nbash\n# Build the wheel file (from repository root)\nuv build\n# Start the MCP server using the local wheel path (adjust path as needed)\nuv run python -m mcp_gitlab_server\n\n\n5) Start and verify: ensure the MCP client can connect and perform basic operations like listing projects or groups. You can then switch to your preferred authentication method by updating the env vars as needed.

Tips and notes:\n- If both GITLAB_OAUTH_TOKEN and GITLAB_TOKEN are provided, the server will prefer GITLAB_OAUTH_TOKEN. You only need to set one.\n- For self-hosted GitLab instances, set GITLAB_URL to your instance URL (e.g., https://gitlab.example.com). If omitted, it defaults to https://gitlab.com.\n- Use scopes like read_api for both personal access tokens and OAuth2 tokens to ensure proper access for the required operations.\n- The server exposes powerful read capabilities for repository contents with filtering, size limits, and branch/ref support to prevent overloading responses.\n- The API surface includes MR analytics, including average/median lifetimes, percentiles, and per-MR breakdowns, which can help with performance and process improvements.\n- When testing locally, you can point to a local wheel as shown in the repository’s testing configuration to isolate development changes from the main package registry.