custom-gitlab

This MCP server provides a GitLab integration for Claude and other MCP-compliant AI assistants. It exposes tools to search for GitLab projects, fetch file contents, and perform common repository operations such as creating or updating files, pushing multiple files in a single commit, and managing issues, merge requests, forks, and branches. The server includes a fixed implementation addressing schema validation issues present in some standard GitLab MCP servers, specifically for the search_repositories tool, to improve reliability when querying GitLab projects.

To use this server, configure it in your Claude or MCP client settings so that the server is reachable as an MCP endpoint. Use the available tools by name to perform the corresponding actions. For example, use search_repositories to locate projects, get_file_contents to read file data, create_or_update_file for single-file edits, push_files for batch commits, and create_issue or create_merge_request to track changes synchronously with GitLab workflows. You can also fork repositories, create new branches, and initialize new projects with create_repository.

• Prerequisites:

  • Node.js (v14 or higher)
  • Access to a GitLab instance with a Personal Access Token (PAT)

• Install dependencies:

  npm install
  

• Configure the MCP server in Claude or your MCP client configuration using the following example:

  {
    "mcpServers": {
      "custom-gitlab": {
        "command": "node",
        "args": [
          "/path/to/custom-gitlab-server/index.js"
        ],
        "env": {
          "GITLAB_PERSONAL_ACCESS_TOKEN": "your-gitlab-token",
          "GITLAB_API_URL": "https://your-gitlab-instance/api/v4"
        }
      }
    }
  }
  

• Run the server as configured by your environment. Ensure the NODE path and index.js location match your deployment.

Environment variables:

• GITLAB_PERSONAL_ACCESS_TOKEN: GitLab PAT with appropriate scopes (api, read_api, read_repository, write_repository as needed).
• GITLAB_API_URL: Base API URL for your GitLab instance (default https://gitlab.com/api/v4 if using GitLab.com).

Common issues:

• Ensure the PAT has the required scopes for the operations you intend to perform.
• Verify network access from the MCP server to your GitLab instance (firewalls, VPNs, etc.).
• If search_repositories returns schema validation errors, confirm you are using the fixed implementation included with this server.
• When configuring in Claude, ensure the index.js path is correct and the environment variables are exposed to the runtime.

Tips:

• Use push_files for batching multiple file changes into a single commit to optimize operations.
• When creating branches or repositories, provide explicit naming conventions to align with your GitLab workflows.