Metadata-Version: 2.4
Name: qodev-gitlab-mcp
Version: 0.2.1
Summary: Production-ready GitLab MCP server exposing projects, merge requests, pipelines, and discussions
Project-URL: Homepage, https://github.com/qodevai/gitlab-mcp
Project-URL: Repository, https://github.com/qodevai/gitlab-mcp
Project-URL: Issues, https://github.com/qodevai/gitlab-mcp/issues
Author: Jan Scheffler
License: MIT
License-File: LICENSE
Keywords: ai,claude,gitlab,mcp,model-context-protocol
Classifier: Development Status :: 5 - Production/Stable
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Software Development :: Libraries
Classifier: Typing :: Typed
Requires-Python: >=3.11
Requires-Dist: fastmcp>=2.2.5
Requires-Dist: qodev-gitlab-api>=0.1.2
Provides-Extra: dev
Requires-Dist: mypy>=1.13.0; extra == 'dev'
Requires-Dist: pytest-asyncio>=0.24.0; extra == 'dev'
Requires-Dist: pytest-cov>=4.1.0; extra == 'dev'
Requires-Dist: pytest-mock>=3.12.0; extra == 'dev'
Requires-Dist: pytest>=8.0.0; extra == 'dev'
Requires-Dist: ruff>=0.8.0; extra == 'dev'
Description-Content-Type: text/markdown

# qodev-gitlab-mcp

A Model Context Protocol (MCP) server for GitLab integration. Exposes projects, merge requests, pipelines, discussions, issues, releases, and more through a standardized interface for AI assistants like Claude.

## Installation

```bash
pip install qodev-gitlab-mcp
```

Or run directly with uvx:

```bash
uvx qodev-gitlab-mcp
```

## Configuration

Set the following environment variables:

```env
# Required
GITLAB_TOKEN=glpat-YOUR-TOKEN-HERE

# Optional (defaults to https://gitlab.com)
GITLAB_URL=https://gitlab.com
```

### Claude Code

Add to your MCP configuration:

```json
{
  "mcpServers": {
    "gitlab": {
      "command": "uvx",
      "args": ["qodev-gitlab-mcp"],
      "env": {
        "GITLAB_TOKEN": "your-token-here",
        "GITLAB_URL": "https://gitlab.com"
      }
    }
  }
}
```

## Features

- Merge request management (create, comment, merge, close, inline comments)
- Pipeline monitoring with `wait_for_pipeline` tool
- Issue tracking (create, update, close, comment)
- Release management
- CI/CD variable management
- File uploads with image support
- Automatic "current" project/branch detection via MCP workspace roots

## Tools

The server exposes the following MCP tools:

### Merge Requests

| Tool | Description |
|------|-------------|
| `create_merge_request` | Create a new merge request |
| `update_merge_request` | Update MR title, description, labels, assignees, reviewers |
| `merge_merge_request` | Merge a merge request |
| `close_merge_request` | Close a merge request (with optional comment) |
| `comment_on_merge_request` | Leave a comment on a merge request |
| `create_inline_comment` | Add an inline comment on a specific line in a MR diff |
| `reply_to_discussion` | Reply to an existing discussion thread |
| `resolve_discussion_thread` | Resolve or unresolve a discussion thread |

### Pipelines

| Tool | Description |
|------|-------------|
| `wait_for_pipeline` | Wait for a pipeline to complete and return results |
| `download_artifact` | Download a job artifact to local filesystem |
| `retry_job` | Retry a failed CI/CD job |

### Issues

| Tool | Description |
|------|-------------|
| `create_issue` | Create a new issue |
| `update_issue` | Update an existing issue |
| `close_issue` | Close an issue |
| `comment_on_issue` | Leave a comment on an issue |

### Releases

| Tool | Description |
|------|-------------|
| `create_release` | Create a new release with tag, description, and assets |

### CI/CD Variables

| Tool | Description |
|------|-------------|
| `set_project_ci_variable` | Create or update a CI/CD variable (upsert) |

### Files

| Tool | Description |
|------|-------------|
| `upload_file` | Upload a file to GitLab for embedding in issues or MRs |

All tools support `project_id="current"` to auto-detect the project from the current working directory. Merge request tools also support `mr_iid="current"` to detect the MR for the current branch.

## Resources

The server exposes the following read-only MCP resources:

### Projects

| Resource URI | Description |
|--------------|-------------|
| `gitlab://projects/` | List all accessible projects |
| `gitlab://projects/{project_id}` | Get project details |

### Merge Requests

| Resource URI | Description |
|--------------|-------------|
| `gitlab://projects/{project_id}/merge-requests/` | List open merge requests |
| `gitlab://projects/{project_id}/merge-requests/{mr_iid}` | Full MR overview (metadata, discussions, changes, commits, pipeline, approvals) |
| `gitlab://projects/{project_id}/merge-requests/{mr_iid}/status` | Lightweight merge-readiness check |
| `gitlab://projects/{project_id}/merge-requests/{mr_iid}/discussions` | MR discussion threads |
| `gitlab://projects/{project_id}/merge-requests/{mr_iid}/changes` | MR diff/changes |
| `gitlab://projects/{project_id}/merge-requests/{mr_iid}/commits` | MR commit history |
| `gitlab://projects/{project_id}/merge-requests/{mr_iid}/approvals` | MR approval status |
| `gitlab://projects/{project_id}/merge-requests/{mr_iid}/pipeline-jobs` | Jobs from the MR's latest pipeline |

### Pipelines & Jobs

| Resource URI | Description |
|--------------|-------------|
| `gitlab://projects/{project_id}/pipelines/` | List recent pipelines |
| `gitlab://projects/{project_id}/pipelines/{pipeline_id}` | Get pipeline details |
| `gitlab://projects/{project_id}/pipelines/{pipeline_id}/jobs` | List jobs in a pipeline |
| `gitlab://projects/{project_id}/jobs/{job_id}/log` | Full job log output |
| `gitlab://projects/{project_id}/jobs/{job_id}/artifacts` | List job artifacts |
| `gitlab://projects/{project_id}/jobs/{job_id}/artifacts/{path}` | Read a specific artifact file |

### Issues

| Resource URI | Description |
|--------------|-------------|
| `gitlab://projects/{project_id}/issues/` | List open issues |
| `gitlab://projects/{project_id}/issues/{issue_iid}` | Get issue details |
| `gitlab://projects/{project_id}/issues/{issue_iid}/notes` | Get issue comments |

### Releases

| Resource URI | Description |
|--------------|-------------|
| `gitlab://projects/{project_id}/releases/` | List all releases |
| `gitlab://projects/{project_id}/releases/{tag_name}` | Get release by tag |

### CI/CD Variables

| Resource URI | Description |
|--------------|-------------|
| `gitlab://projects/{project_id}/variables/` | List CI/CD variables (metadata only, values hidden) |
| `gitlab://projects/{project_id}/variables/{key}` | Get variable metadata by key |

### Help

| Resource URI | Description |
|--------------|-------------|
| `gitlab://help` | Server capabilities and usage guide |

## License

MIT
