Metadata-Version: 2.4
Name: iflow-mcp_adit-999_gitlab-mcp-server
Version: 0.2.1
Summary: GitLab MCP (Model Context Protocol) server for interacting with GitLab API through AI Clients
Project-URL: Homepage, https://github.com/Adit-999/gitlab-mcp
Project-URL: Documentation, https://github.com/Adit-999/gitlab-mcp#readme
Author-email: Adit pal Singh <aditpalsing@gmail.com>
License: MIT License
        
        Copyright (c) 2025 Adit Pal Singh
        
        Permission is hereby granted, free of charge, to any person obtaining a copy
        of this software and associated documentation files (the "Software"), to deal
        in the Software without restriction, including without limitation the rights
        to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
        copies of the Software, and to permit persons to whom the Software is
        furnished to do so, subject to the following conditions:
        
        The above copyright notice and this permission notice shall be included in all
        copies or substantial portions of the Software.
        
        THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
        IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
        FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
        AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
        LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
        OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
        SOFTWARE.
License-File: LICENSE
Keywords: ai,gitlab,mcp,server
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3.11
Classifier: Topic :: Software Development :: Libraries :: Application Frameworks
Requires-Python: >=3.11
Requires-Dist: asyncio>=3.4.3
Requires-Dist: dotenv>=0.9.9
Requires-Dist: mcp[cli]>=1.6.0
Requires-Dist: pydantic-settings>=2.8.1
Requires-Dist: pydantic>=2.11.3
Provides-Extra: dev
Requires-Dist: black>=24.2.0; extra == 'dev'
Requires-Dist: flake8>=7.0.0; extra == 'dev'
Requires-Dist: mypy>=1.8.0; extra == 'dev'
Requires-Dist: pytest-asyncio>=0.23.5; extra == 'dev'
Requires-Dist: pytest>=8.0.0; extra == 'dev'
Provides-Extra: ruff
Requires-Dist: ruff>=0.11.5; extra == 'ruff'
Description-Content-Type: text/markdown

# GitLab MCP Server

A MCP (Model Context Protocol) server for interacting with GitLab API. This server provides a set of tools that allow AI clients to perform operations on GitLab repositories, issues, merge requests, and more. All operations support both synchronous and asynchronous execution patterns.

## Installation

### Using uv (Recommended)

```bash
# Clone the repository
git clone https://github.com/Adit-999/gitlab-mcp.git
cd gitlab-mcp

# Install dependencies using uv
uv sync
```

### Using pip

```bash
# Clone the repository
git clone https://github.com/Adit-999/gitlab-mcp.git
cd gitlab-mcp

# Create and activate a virtual environment
python -m venv .venv
source .venv/bin/activate  # On Windows: .venv\Scripts\activate

# Install dependencies
pip install -e .
```

## Configuration

The GitLab MCP server requires two environment variables to function properly:

1. `GITLAB_PERSONAL_ACCESS_TOKEN` - For authentication with GitLab API
2. `GITLAB_API_URL` - The base URL for the GitLab API

### Option 1: Environment Variables

Create a `.env` file in the project root directory with these variables:

```
GITLAB_PERSONAL_ACCESS_TOKEN=your_personal_access_token
GITLAB_API_URL=https://gitlab.com
```

### Option 2: MCP Configuration

You can also configure the MCP server in your MCP JSON configuration file:

```json
{
  "mcpServers": {
    "gitlab-mcp": {
      "command": "uv",
      "args": ["run", "--with", "mcp[cli]", "mcp", "run", "/path/to/gitlab-mcp/server.py"],
      "env": {
        "GITLAB_PERSONAL_ACCESS_TOKEN": "your_personal_access_token",
        "GITLAB_API_URL": "https://gitlab.com"
      }
    }
  }
}
```

### Configure with uv for Claude Desktop

```bash
uv run mcp install server.py
```
## Project Structure

The project follows a modular, domain-driven architecture:

```
gitlab-mcp/
├── src/                           # Source code
│   ├── api/                       # API interaction layer
│   │   ├── rest_client.py         # GitLab REST API client
│   │   ├── exceptions.py          # API exception definitions
│   ├── schemas/                   # Data models and validation
│   │   ├── base.py                # Base schema classes
│   │   ├── repositories.py        # Repository data models
│   │   ├── branches.py            # Branch data models
│   │   ├── issues.py              # Issue data models
│   │   ├── merge_requests.py      # Merge request data models
│   │   ├── groups.py              # Group data models
│   │   └── search.py              # search data models
│   ├── services/                  # Business logic layer
│   │   ├── repositories.py        # Repository operations
│   │   ├── branches.py            # Branch operations
│   │   ├── issues.py              # Issue operations
│   │   ├── merge_requests.py      # Merge request operations
│   │   ├── groups.py              # Group operations
│   │   └── search.py              # search operations
│   └── tools/                     # MCP tool implementations
│       ├── repositories.py        # Repository tools
│       ├── branches.py            # Branch tools
│       ├── issues.py              # Issue tools
│       ├── merge_requests.py      # Merge request tools
│       ├── groups.py              # Group tools
│       └── search.py              # search tools
├── server.py                      # Main MCP server entry point
```

This architecture provides several benefits:

- **Separation of concerns**: Each module has a clear responsibility
- **Type safety**: Pydantic schemas ensure data validation
- **Maintainability**: Domain-driven organization makes code easier to navigate
- **Extensibility**: New features can be added by following the established patterns
- **Async support**: All operations are available in both synchronous and asynchronous versions

## Available Tools

The server provides the following tools for interacting with GitLab:

### Repository Management

- `create_repository`: Create a new GitLab repository
- `list_repository_tree`: List the contents of a repository tree

### Branch Operations

- `create_branch`: Create a new branch in a GitLab repository
- `list_branches`: List branches in a GitLab repository
- `get_branch`: Get details for a specific GitLab branch
- `delete_branch`: Delete a branch from a GitLab repository
- `delete_merged_branches`: Delete all merged branches from a GitLab repository
- `protect_branch`: Protect a branch in a GitLab repository
- `unprotect_branch`: Remove protection from a branch in a GitLab repository
- `get_default_branch_ref`: Get the default branch reference for a GitLab repository

### File Operations

- `create_file`: Create a new file in a GitLab repository
- `get_file_contents`: Retrieve the contents of a file from a GitLab repository
- `update_file`: Update an existing file in a GitLab repository
- `delete_file`: Delete a file from a GitLab repository

### Issue Management

- `create_issue`: Create a new issue in a GitLab repository
- `list_all_issues`: List all issues the authenticated user has access to
- `get_issue`: Get details for a specific GitLab issue
- `close_issue`: Close a GitLab issue
- `delete_issue`: Delete an issue from a GitLab repository
- `move_issue`: Move an issue to a different project
- `comment_on_issue`: Add a comment to a GitLab issue
- `list_issue_comments`: List comments for a GitLab issue

### Merge Request Operations

- `create_merge_request`: Create a new merge request in a GitLab repository
- `list_merge_requests`: List merge requests for a GitLab project
- `get_merge_request`: Get details for a specific GitLab merge request
- `merge_merge_request`: Merge a GitLab merge request
- `update_merge_request`: Update an existing merge request in a GitLab repository.
- `delete_merge_request`: Delete a merge request from a GitLab repository.
- `merge_request_changes`: Get the changes for a specific merge request.
- `create_merge_request_comment`: Add a comment to a GitLab merge request.

### Job Operations

- `get_job_logs`: Get logs from a GitLab job

### Group Operations

- `list_groups`: List GitLab groups
- `get_group`: Get a specific GitLab group
- `get_group_by_project_namespace`: Get a GitLab group based on a project namespace

### Search Tools

- `search_globally`: Search across all GitLab resources (currently supports projects and files/blobs).
- `search_project`: Search within a specific project (currently supports projects and files/blobs).
- `search_group`: Search within a specific group (currently supports projects and files/blobs).

## Troubleshooting

### Common Issues

- **GitLab API Authentication Errors**: Ensure your `GITLAB_PERSONAL_ACCESS_TOKEN` has the necessary permissions and is correctly set in your environment variables.
- **NoneType errors**: Some functions may encounter issues when handling empty results. If you encounter these errors, please report them with detailed steps to reproduce.

## License

This project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.
