GitLab MCP Server for AgenticLedger

A Model Context Protocol (MCP) server that enables AI agents to interact with GitLab repositories, monitor documentation changes, and manage issues and merge requests.

Overview

This MCP server provides comprehensive GitLab integration for the AgenticLedger platform, enabling AI agents to:

• Monitor Documentation Changes: Track commits, compare branches, and detect file modifications
• Read Repository Contents: Access files, directory structures, and wiki pages
• Manage Issues & MRs: Create and track issues, merge requests, and comments
• Search Across GitLab: Find projects, code, commits, and more

Authentication Pattern

• [x] API Key (Direct Personal Access Token)

Token Format

accessToken: "glpat-xxxxxxxxxxxxxxxxxxxx"

GitLab Personal Access Token (PAT) with appropriate scopes:

• read_api - For read-only operations
• read_repository - For file access
• api - For full access (issues, MRs, wikis)

Creating a Token

1. Go to GitLab > Settings > Access Tokens
2. Create a new token with required scopes
3. Copy the token (starts with glpat-)

Installation

# Clone the repository
git clone https://github.com/oregpt/Agenticledger_MCP_Gitlab.git
cd Agenticledger_MCP_Gitlab

# Install dependencies
npm install

# Build
npm run build

Configuration

For Claude Code / MCP Clients

Add to your MCP configuration:

{
  "mcpServers": {
    "gitlab": {
      "command": "node",
      "args": ["path/to/GitlabMCP/dist/index.js"],
      "env": {
        "GITLAB_API_URL": "https://gitlab.com/api/v4"
      }
    }
  }
}

Environment Variables

Variable	Required	Default	Description
GITLAB_API_URL	No	https://gitlab.com/api/v4	GitLab API base URL (for self-hosted instances)

Available Tools

Project Operations

gitlab_search_projects

Description: Search for GitLab projects by name or description.

Parameters:

• accessToken (string, required): GitLab Personal Access Token
• search (string, required): Search query
• page (number, optional): Page number
• per_page (number, optional): Results per page (1-100)

Example:

{
  "accessToken": "glpat-xxxx",
  "search": "documentation",
  "per_page": 10
}

gitlab_get_project

Description: Get detailed project information.

Parameters:

• accessToken (string, required): GitLab PAT
• project_id (string, required): Project ID or URL-encoded path

gitlab_list_group_projects

Description: List all projects in a group.

Parameters:

• accessToken (string, required): GitLab PAT
• group_id (string, required): Group ID or path
• include_subgroups (boolean, optional): Include subgroup projects
• search (string, optional): Filter by name
• order_by (string, optional): Sort field
• sort (string, optional): asc or desc

---

File Operations

gitlab_get_file_contents

Description: Read file contents from a repository. Essential for documentation monitoring.

Parameters:

• accessToken (string, required): GitLab PAT
• project_id (string, required): Project ID
• file_path (string, required): Path to file (e.g., "docs/README.md")
• ref (string, optional): Branch, tag, or commit SHA

Response:

{
  "success": true,
  "data": {
    "file_name": "README.md",
    "file_path": "docs/README.md",
    "content": "# Documentation\n...",
    "encoding": "base64",
    "ref": "main"
  }
}

gitlab_get_tree

Description: List files and directories in a repository path.

Parameters:

• accessToken (string, required): GitLab PAT
• project_id (string, required): Project ID
• path (string, optional): Directory path
• ref (string, optional): Branch/tag/SHA
• recursive (boolean, optional): List recursively

gitlab_create_or_update_file

Description: Create or update a file with a commit.

Parameters:

• accessToken (string, required): GitLab PAT
• project_id (string, required): Project ID
• file_path (string, required): Target file path
• branch (string, required): Target branch
• content (string, required): File content
• commit_message (string, required): Commit message

---

Commit Operations (Critical for Monitoring)

gitlab_list_commits

Description: List recent commits. Primary tool for detecting documentation changes.

Parameters:

• accessToken (string, required): GitLab PAT
• project_id (string, required): Project ID
• ref_name (string, optional): Branch or tag
• since (string, optional): ISO 8601 date
• until (string, optional): ISO 8601 date
• path (string, optional): Filter by file path
• author (string, optional): Filter by author email
• with_stats (boolean, optional): Include stats

Example - Monitor docs folder:

{
  "accessToken": "glpat-xxxx",
  "project_id": "12345",
  "path": "docs/",
  "since": "2024-01-01T00:00:00Z",
  "with_stats": true
}

gitlab_get_commit_diff

Description: Get file changes for a specific commit.

Parameters:

• accessToken (string, required): GitLab PAT
• project_id (string, required): Project ID
• sha (string, required): Commit SHA

gitlab_compare

Description: Compare two branches/tags/commits.

Parameters:

• accessToken (string, required): GitLab PAT
• project_id (string, required): Project ID
• from (string, required): Source ref
• to (string, required): Target ref

---

Activity Monitoring

gitlab_get_project_events

Description: Get recent project activity. Best tool for real-time monitoring.

Parameters:

• accessToken (string, required): GitLab PAT
• project_id (string, required): Project ID
• action (string, optional): Filter by action type (pushed, commented, etc.)
• target_type (string, optional): Filter by target (issue, merge_request, etc.)
• after (string, optional): Events after this date (ISO 8601)
• before (string, optional): Events before this date

Example - Monitor push events:

{
  "accessToken": "glpat-xxxx",
  "project_id": "12345",
  "action": "pushed",
  "after": "2024-12-01T00:00:00Z"
}

---

Issue Operations

gitlab_list_issues

List project issues with filtering.

gitlab_get_issue

Get specific issue details.

gitlab_create_issue

Create a new issue.

gitlab_list_issue_notes

List comments on an issue.

---

Merge Request Operations

gitlab_list_merge_requests

List MRs with filtering.

gitlab_get_merge_request

Get MR details.

gitlab_get_merge_request_changes

Get file changes in an MR.

gitlab_create_merge_request

Create a new MR.

---

Wiki Operations

gitlab_list_wiki_pages

List all wiki pages.

gitlab_get_wiki_page

Get wiki page content.

gitlab_create_wiki_page

Create a wiki page.

gitlab_update_wiki_page

Update a wiki page.

---

Search Operations

gitlab_search

Description: Search across GitLab.

Parameters:

• accessToken (string, required): GitLab PAT
• search (string, required): Search query
• scope (string, optional): projects, issues, merge_requests, blobs, commits, etc.
• project_id (string, optional): Limit to project
• group_id (string, optional): Limit to group

---

Response Format

All tools return a standardized response:

{
  success: boolean;
  data?: any;      // Present on success
  error?: string;  // Present on failure
}

Success Example:

{
  "success": true,
  "data": {
    "id": 12345,
    "name": "my-project",
    "description": "..."
  }
}

Error Example:

{
  "success": false,
  "error": "Resource not found: /projects/99999"
}

Testing

# Run unit tests
npm test

# Run integration tests (requires GITLAB_TEST_TOKEN)
GITLAB_TEST_TOKEN=glpat-xxx npm run test:integration

Use Case: Documentation Monitoring

This is the primary use case for this MCP server. Here's how to monitor a customer's documentation repo:

Workflow

1. Initial Scan: Use gitlab_get_tree to discover documentation files
2. Monitor Changes: Periodically call gitlab_get_project_events or gitlab_list_commits
3. Fetch Updates: When changes detected, use gitlab_get_file_contents to read updated files
4. Process: Feed updated content to your D7 data pipeline

Example Monitoring Script

// 1. Get recent commits affecting docs
const commits = await gitlab_list_commits({
  accessToken: "glpat-xxx",
  project_id: "customer/docs-repo",
  path: "docs/",
  since: lastCheckTime,
  with_stats: true
});

// 2. For each new commit, get the changes
for (const commit of commits.data) {
  const diff = await gitlab_get_commit_diff({
    accessToken: "glpat-xxx",
    project_id: "customer/docs-repo",
    sha: commit.id
  });

  // 3. Process changed files
  for (const file of diff.data) {
    if (file.new_path.startsWith('docs/')) {
      const content = await gitlab_get_file_contents({
        accessToken: "glpat-xxx",
        project_id: "customer/docs-repo",
        file_path: file.new_path
      });
      // Update your knowledge base
    }
  }
}

Platform Integration Notes

Self-Hosted GitLab

Set GITLAB_API_URL to your instance:

{
  "env": {
    "GITLAB_API_URL": "https://gitlab.yourcompany.com/api/v4"
  }
}

Rate Limits

GitLab has rate limits:

• Authenticated: 2000 requests/minute
• Consider pagination for large datasets
• Use since filters to reduce response size

Token Scopes

Minimum required scopes:

Operation	Required Scope
Read files	read_repository
Read issues/MRs	read_api
Create issues/MRs	api
Write files	api

License

MIT

Contributing

1. Fork the repository
2. Create a feature branch
3. Make changes
4. Run tests
5. Submit a pull request

Support

For issues, please file a GitHub issue at: https://github.com/oregpt/Agenticledger_MCP_Gitlab/issues