@zephyr-mcp/gitlab-gql

A GitLab integration server built on the Model Context Protocol (MCP) framework, providing powerful integration capabilities with GitLab instances. This service can function as a plugin for large language models like Claude, enabling models to securely access GitLab resources through a GraphQL API.

Key Features

• GitLab GraphQL API Integration: Seamless access to any GitLab instance's GraphQL API with robust query capabilities
• Project Data Masking: Automatic handling of sensitive data based on project visibility, supporting multiple masking modes to protect private project information
• Smart URL Processing: Automatic recognition and preservation of GitLab URLs while masking non-GitLab sensitive URLs
• Cache Management: Efficient caching of project visibility states to reduce unnecessary API requests and improve performance
• Diverse Query Support: Flexible queries for various GitLab resources including projects, users, groups, and merge requests

Quick Start

# Install dependencies
npm install

# Build the project
npm run build

# Start the service
npm run start

Environment Variables Configuration

The service requires the following environment variables:

GITLAB_API_URL=https://your-gitlab-instance.com  # GitLab instance URL
GITLAB_TOKEN=your_access_token                   # GitLab access token
GITLAB_MASK_MODE=simple                          # Masking mode (options: simple or content, default: simple)

Tool Documentation

GitlabGqlTool

The GitLab GraphQL query tool allows LLMs to execute GraphQL queries to access GitLab data and functionality. The tool supports two masking modes to protect sensitive information while intelligently recognizing GitLab URLs to ensure query result usability.

Masking Modes

The tool supports two masking modes controlled by the GITLAB_MASK_MODE environment variable:

1. simple (default): Private projects only return id, name, webUrl and visibility fields, with all other information completely hidden
2. content: Private projects return all fields but sensitive content (such as paths, descriptions, usernames) is masked with "***"

URL Recognition Optimization

The tool features smart URL processing:

• Automatically recognizes and preserves GitLab domain URLs (based on GITLAB_API_URL environment variable)
• Masks non-GitLab URLs, preserving only the protocol and domain while hiding paths

Usage Examples

// Search for projects
await mcp.runTool("gitlab_gql", {
  query: "{projects(search: \"project name\") { nodes { id name webUrl visibility } }}",
  queryType: "projects"
});

// Get a specific project
await mcp.runTool("gitlab_gql", {
  query: "{project(fullPath: \"namespace/project\") { id name webUrl visibility }}",
  queryType: "project",
  projectPath: "namespace/project"
});

// User query
await mcp.runTool("gitlab_gql", {
  query: "{user(username: \"username\") { id name username avatarUrl }}",
  queryType: "user",
  requiresVisibility: false
});

// Query projects a user contributes to
await mcp.runTool("gitlab_gql", {
  query: "{user(username: \"username\") { projects(first: 5) { nodes { id name webUrl } } }}",
  queryType: "user",
  requiresVisibility: false
});

// Query a project's merge requests
await mcp.runTool("gitlab_gql", {
  query: "{project(fullPath: \"namespace/project\") { mergeRequests(assigneeUsername: \"username\", first: 5) { nodes { id title state } } }}",
  queryType: "project",
  projectPath: "namespace/project"
});

GitlabGqlResource

Provides access to cached project information, supporting the file:// protocol to allow LLMs to reference previously retrieved GitLab data, improving conversation continuity.

Project Structure

gitlab-gql/
├── src/
│   ├── tools/
│   │   ├── GitlabGqlTool.ts        # GitLab GraphQL query tool
│   │   └── GitlabGqlResource.ts    # GitLab cached resource access
│   └── index.ts                    # Server entry point
├── package.json
└── tsconfig.json

Usage in Claude Desktop Client

NPM Installation

After installation, add the following configuration to the Claude desktop client configuration file:

MacOS: ~/Library/Application Support/Claude/claude_desktop_config.json
Windows: %APPDATA%/Claude/claude_desktop_config.json

{
  "mcpServers": {
    "@zephyr-mcp/gitlab-gql": {
      "command": "npx",
      "args": ["-y", "@zephyr-mcp/gitlab-gql"]
    }
  }
}

Learn More

• MCP Framework Documentation
• GitLab GraphQL API Documentation