@mjwegenka/gitlab-snippet-mcp v1.3.0

GitLab Snippet MCP Server

MCP Server for interacting with GitLab Snippets. This package provides an integration between the Model Context Protocol (MCP) and the GitLab Snippets API. Supports both personal snippets and project snippets.

Installation

npm install -g @mjwegenka/gitlab-snippet-mcp

Usage

Configuration

1. Create a GitLab personal access token with api permissions

2. Configure the token in the MCP configuration file:

{
  "mcpServers": {
    "gitlab": {
      "command": "npx",
      "args": ["@mjwegenka/gitlab-snippet-mcp"],
      "env": {
        "GITLAB_TOKEN": "your-token",
        "GITLAB_URL": "https://gitlab.com/api/v4"
      }
    }
  }
}

Working with Snippets

This MCP server supports both personal snippets and project snippets from GitLab.

Project Identification

For operations involving project snippets, you can specify the project in two ways:

1. Using a numeric project ID:

   "projectId": "123"

2. Using the project path (the server will automatically resolve it to an ID):

   "projectId": "mygroup/myproject"

Project paths with special characters are properly handled and URL-encoded automatically.

Available Operations

Get Project ID from Name

{
  "name": "get_project_id",
  "arguments": {
    "projectName": "mygroup/myproject"
  }
}

This returns the numeric project ID which you can optionally use in other operations.

Create a Snippet

Create a personal snippet:

{
  "name": "create_snippet",
  "arguments": {
    "title": "My Snippet",
    "description": "A simple code snippet",
    "visibility": "private", // "private", "internal", or "public"
    "files": [
      {
        "file_path": "example.js",
        "content": "console.log('Hello, snippet!');"
      }
    ]
  }
}

Create a project snippet:

{
  "name": "create_snippet",
  "arguments": {
    "projectId": "mygroup/myproject", // or numeric ID: "123"
    "title": "My Project Snippet",
    "description": "A snippet in my project",
    "visibility": "private",
    "files": [
      {
        "file_path": "example.js",
        "content": "console.log('Hello, project snippet!');"
      }
    ]
  }
}

Get a Snippet

Get a personal snippet:

{
  "name": "get_snippet",
  "arguments": {
    "snippetId": "456"
  }
}

Get a project snippet:

{
  "name": "get_snippet",
  "arguments": {
    "snippetId": "456",
    "projectId": "mygroup/myproject" // or numeric ID: "123"
  }
}

Get Snippet Raw Content

{
  "name": "get_snippet_raw_content",
  "arguments": {
    "snippetId": "456",
    "projectId": "mygroup/myproject", // Optional, for project snippets
    "preserveLineEndings": true // Optional, preserve original line endings
  }
}

This returns the complete raw content of the snippet. By default, the content is returned with Linux-style line endings (LF). Setting preserveLineEndings to true will return the content with its original line endings preserved (which might be CRLF if created using the GitLab web interface).

Get Snippet File Raw Content

{
  "name": "get_snippet_file_raw_content",
  "arguments": {
    "snippetId": "456",
    "filePath": "example.js",
    "ref": "master", // Optional, defaults to "master"
    "projectId": "mygroup/myproject", // Optional, for project snippets
    "preserveLineEndings": true // Optional, preserve original line endings
  }
}

This returns the raw content of a specific file within a snippet. Like with get_snippet_raw_content, the preserveLineEndings parameter controls whether the original line endings are preserved.

Update a Snippet

{
  "name": "update_snippet",
  "arguments": {
    "snippetId": "456",
    "projectId": "mygroup/myproject", // Optional, for project snippets
    "title": "Updated Title", // Optional
    "description": "Updated description", // Optional
    "visibility": "internal", // Optional
    "files": [ // Optional
      {
        "action": "update", // "create", "update", "delete", or "move"
        "file_path": "example.js",
        "content": "console.log('Updated content!');"
      },
      {
        "action": "create",
        "file_path": "new-file.js",
        "content": "console.log('New file!');"
      },
      {
        "action": "move",
        "file_path": "new-path.js",
        "previous_path": "old-path.js"
      },
      {
        "action": "delete",
        "file_path": "to-be-deleted.js"
      }
    ]
  }
}

Delete a Snippet

{
  "name": "delete_snippet",
  "arguments": {
    "snippetId": "456",
    "projectId": "mygroup/myproject" // Optional, for project snippets
  }
}

List User Snippets

{
  "name": "list_snippets",
  "arguments": {
    "projectId": "mygroup/myproject", // Optional, for project snippets
    "page": 1, // Optional, default: 1
    "per_page": 20, // Optional, default: 30
    "created_after": "2023-01-01T00:00:00Z", // Optional, ISO 8601 format
    "created_before": "2023-12-31T23:59:59Z" // Optional, ISO 8601 format
  }
}

List Public Snippets

{
  "name": "list_public_snippets",
  "arguments": {
    "page": 1, // Optional, default: 1
    "per_page": 20, // Optional, default: 30
    "created_after": "2023-01-01T00:00:00Z", // Optional, ISO 8601 format
    "created_before": "2023-12-31T23:59:59Z" // Optional, ISO 8601 format
  }
}

List All Accessible Snippets

{
  "name": "list_all_snippets",
  "arguments": {
    "page": 1, // Optional, default: 1
    "per_page": 20, // Optional, default: 30
    "created_after": "2023-01-01T00:00:00Z", // Optional, ISO 8601 format
    "created_before": "2023-12-31T23:59:59Z", // Optional, ISO 8601 format
    "repository_storage": "default" // Optional, admin only
  }
}

Error Handling

The server provides meaningful error messages in case of issues. Common error scenarios include:

• Invalid GitLab token or insufficient permissions
• Project not found (when using an invalid project name or ID)
• Snippet not found
• Validation errors for request parameters
• Rate limiting or API access issues

Error responses include an error message and, when available, additional details from the GitLab API.

Special Characters and URL Encoding

This server properly handles special characters in project names, snippet IDs, and file paths by automatically URL-encoding them when making requests to the GitLab API. This ensures compatibility with projects and snippets that contain spaces, slashes, dots, and other special characters in their names or paths.