mcp-gitlab 0.0.1__tar.gz

mcp_gitlab-0.0.1/.env.example

@@ -0,0 +1,8 @@
+# GitLab instance URL (required)
+GITLAB_URL=https://gitlab.example.com
+
+# Personal access token with api scope (required)
+GITLAB_TOKEN=glpat-xxxxxxxxxxxxxxxxxxxx
+
+# Optional: set to "true" to disable write operations
+# GITLAB_READ_ONLY=false

mcp_gitlab-0.0.1/.github/workflows/lint.yml

@@ -0,0 +1,11 @@
+name: Lint
+on: [push, pull_request]
+jobs:
+  lint:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: astral-sh/setup-uv@v5
+      - run: uv sync
+      - run: uv run ruff check .
+      - run: uv run ruff format --check .

mcp_gitlab-0.0.1/.github/workflows/publish.yml

@@ -0,0 +1,39 @@
+name: Publish to PyPI
+
+on:
+  push:
+    tags:
+      - "v*"
+
+jobs:
+  build-n-publish:
+    runs-on: ubuntu-latest
+    environment: pypi
+    permissions:
+      id-token: write
+      contents: write
+
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Install uv
+        uses: astral-sh/setup-uv@v5
+        with:
+          version: "latest"
+
+      - name: Set up Python
+        run: uv python install
+
+      - name: Build package
+        run: uv build
+
+      - name: Publish to PyPI
+        uses: pypa/gh-action-pypi-publish@release/v1
+
+      - name: Create GitHub Release
+        uses: softprops/action-gh-release@v2
+        with:
+          files: dist/*
+          generate_release_notes: true
+        env:
+          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}

mcp_gitlab-0.0.1/.github/workflows/release.yml

@@ -0,0 +1,91 @@
+name: Semantic Release
+
+on:
+  workflow_dispatch:
+    inputs:
+      bump:
+        description: "Version bump type"
+        required: true
+        type: choice
+        options:
+          - patch
+          - minor
+          - major
+      dry_run:
+        description: "Dry run (no tag/push)"
+        required: false
+        type: boolean
+        default: false
+
+jobs:
+  release:
+    runs-on: ubuntu-latest
+    permissions:
+      contents: write
+
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          fetch-depth: 0
+
+      - name: Install uv
+        uses: astral-sh/setup-uv@v5
+        with:
+          version: "latest"
+
+      - name: Set up Python
+        run: uv python install
+
+      - name: Get current version
+        id: current
+        run: |
+          version=$(grep '^version' pyproject.toml | head -1 | sed 's/.*"\(.*\)"/\1/')
+          echo "version=$version" >> "$GITHUB_OUTPUT"
+          echo "Current version: $version"
+
+      - name: Compute next version
+        id: next
+        run: |
+          IFS='.' read -r major minor patch <<< "${{ steps.current.outputs.version }}"
+          case "${{ inputs.bump }}" in
+            major) major=$((major + 1)); minor=0; patch=0 ;;
+            minor) minor=$((minor + 1)); patch=0 ;;
+            patch) patch=$((patch + 1)) ;;
+          esac
+          version="$major.$minor.$patch"
+          echo "version=$version" >> "$GITHUB_OUTPUT"
+          echo "Next version: $version"
+
+      - name: Update pyproject.toml version
+        run: |
+          sed -i "s/^version = \".*\"/version = \"${{ steps.next.outputs.version }}\"/" pyproject.toml
+          cat pyproject.toml | grep '^version'
+
+      - name: Verify build
+        run: uv build
+
+      - name: Commit and tag
+        if: ${{ !inputs.dry_run }}
+        run: |
+          git config user.name "github-actions[bot]"
+          git config user.email "github-actions[bot]@users.noreply.github.com"
+          git add pyproject.toml
+          git commit -m "chore(release): ${{ steps.next.outputs.version }}"
+          git tag "v${{ steps.next.outputs.version }}"
+          git push origin main
+          git push origin "v${{ steps.next.outputs.version }}"
+
+      - name: Dry run summary
+        if: ${{ inputs.dry_run }}
+        run: |
+          echo "## Dry Run Summary" >> "$GITHUB_STEP_SUMMARY"
+          echo "- Current: ${{ steps.current.outputs.version }}" >> "$GITHUB_STEP_SUMMARY"
+          echo "- Next: ${{ steps.next.outputs.version }}" >> "$GITHUB_STEP_SUMMARY"
+          echo "- Bump: ${{ inputs.bump }}" >> "$GITHUB_STEP_SUMMARY"
+          echo "- No changes pushed." >> "$GITHUB_STEP_SUMMARY"
+
+      - name: Release summary
+        if: ${{ !inputs.dry_run }}
+        run: |
+          echo "## Release v${{ steps.next.outputs.version }}" >> "$GITHUB_STEP_SUMMARY"
+          echo "- Tag pushed. Publish workflow will deploy to PyPI." >> "$GITHUB_STEP_SUMMARY"

mcp_gitlab-0.0.1/.github/workflows/tests.yml

@@ -0,0 +1,21 @@
+name: Tests
+on: [push, pull_request]
+jobs:
+  test:
+    runs-on: ubuntu-latest
+    strategy:
+      matrix:
+        python-version: ["3.10", "3.11", "3.12", "3.13"]
+    steps:
+      - uses: actions/checkout@v4
+      - uses: astral-sh/setup-uv@v5
+        with:
+          python-version: ${{ matrix.python-version }}
+      - run: uv sync --all-extras
+      - run: uv run pytest --cov --cov-report=xml
+      - name: Upload coverage
+        if: matrix.python-version == '3.13'
+        uses: codecov/codecov-action@v4
+        with:
+          file: coverage.xml
+        continue-on-error: true

mcp_gitlab-0.0.1/.gitignore

@@ -0,0 +1,34 @@
+__pycache__/
+*.py[cod]
+*$py.class
+*.so
+dist/
+build/
+*.egg-info/
+*.egg
+.eggs/
+.venv/
+venv/
+env/
+.env
+.env.local
+*.log
+.mypy_cache/
+.pytest_cache/
+.ruff_cache/
+htmlcov/
+.coverage
+.coverage.*
+coverage.xml
+*.cover
+.tox/
+.nox/
+.hypothesis/
+*.swp
+*.swo
+*~
+.DS_Store
+Thumbs.db
+.idea/
+.vscode/
+*.iml

mcp_gitlab-0.0.1/AGENTS.md

@@ -0,0 +1,34 @@
+# mcp-gitlab — Agent Context
+
+MCP server providing 65+ tools for the GitLab REST API v4.
+
+## Architecture
+
+- **Entry point**: `src/mcp_gitlab/__init__.py` — click CLI, loads env, runs FastMCP server
+- **Client**: `src/mcp_gitlab/client.py` — async httpx client with all GitLab API methods
+- **Tools**: `src/mcp_gitlab/servers/gitlab.py` — all FastMCP tool registrations
+- **Models**: `src/mcp_gitlab/models/` — Pydantic models for typed API responses
+- **Config**: `src/mcp_gitlab/config.py` — `GitLabConfig` dataclass from env vars
+- **Exceptions**: `src/mcp_gitlab/exceptions.py` — `GitLabApiError`, `GitLabAuthError`, etc.
+
+## Patterns
+
+- All tools are `async def` returning JSON strings
+- Error handling: try/except wrapping every tool, returning `{"error": ...}` JSON
+- Write access control: `_check_write(ctx)` raises `GitLabWriteDisabledError` when `GITLAB_READ_ONLY=true`
+- Tags: every tool tagged with `{"gitlab", "<category>", "read"|"write"}`
+- Parameters use `Annotated[type, Field(description=...)]`
+- Client uses httpx with `PRIVATE-TOKEN` header auth
+- Project/group IDs can be numeric or URL-encoded paths
+
+## Tool Categories
+
+Projects (4), Approvals (10), Groups (6), Branches (3), Commits (4), Merge Requests (9), MR Notes (6), MR Discussions (4), Pipelines (5), Jobs (4), Tags (4), Releases (5), CI/CD Variables (8), Issues (5)
+
+## Environment Variables
+
+- `GITLAB_URL` (required) — GitLab instance base URL
+- `GITLAB_TOKEN` or `GITLAB_PAT` (required) — Personal access token
+- `GITLAB_READ_ONLY` — disable mutations
+- `GITLAB_TIMEOUT` — request timeout seconds
+- `GITLAB_SSL_VERIFY` — SSL verification toggle

mcp_gitlab-0.0.1/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Vis
+
+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.

mcp_gitlab-0.0.1/PKG-INFO

@@ -0,0 +1,245 @@
+Metadata-Version: 2.4
+Name: mcp-gitlab
+Version: 0.0.1
+Summary: MCP server for GitLab API — projects, MRs, pipelines, CI/CD variables, approvals, and more
+Author: vish288
+License: MIT
+License-File: LICENSE
+Keywords: ai,automation,gitlab,llm,mcp
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Requires-Python: >=3.10
+Requires-Dist: click>=8.1.7
+Requires-Dist: fastmcp>=2.13.0
+Requires-Dist: httpx>=0.28.0
+Requires-Dist: pydantic<3.0,>=2.10.0
+Requires-Dist: python-dotenv>=1.0.1
+Description-Content-Type: text/markdown
+
+# mcp-gitlab
+
+MCP server for the GitLab REST API. Provides 65+ tools for projects, merge requests, pipelines, CI/CD variables, approvals, issues, and more.
+
+Built with [FastMCP](https://github.com/jlowin/fastmcp), [httpx](https://www.python-httpx.org/), and [Pydantic](https://docs.pydantic.dev/).
+
+## Installation
+
+```bash
+# From PyPI
+uv pip install mcp-gitlab
+
+# From source
+uv pip install git+https://github.com/vish288/mcp-gitlab.git
+```
+
+## Configuration
+
+Set these environment variables:
+
+| Variable | Required | Description |
+|----------|----------|-------------|
+| `GITLAB_URL` | Yes | GitLab instance URL (e.g. `https://gitlab.example.com`) |
+| `GITLAB_TOKEN` | Yes | Personal access token with `api` scope |
+| `GITLAB_READ_ONLY` | No | Set to `true` to disable write operations |
+| `GITLAB_TIMEOUT` | No | Request timeout in seconds (default: 30) |
+| `GITLAB_SSL_VERIFY` | No | Set to `false` to skip SSL verification |
+
+## Usage
+
+### Claude Code / Cursor
+
+Add to your MCP config (`~/.claude/settings.json` or `.cursor/mcp.json`):
+
+```json
+{
+  "mcpServers": {
+    "gitlab": {
+      "command": "uvx",
+      "args": ["mcp-gitlab"],
+      "env": {
+        "GITLAB_URL": "https://gitlab.example.com",
+        "GITLAB_TOKEN": "glpat-xxxxxxxxxxxxxxxxxxxx"
+      }
+    }
+  }
+}
+```
+
+### Standalone
+
+```bash
+# stdio transport (default)
+mcp-gitlab
+
+# HTTP transport
+mcp-gitlab --transport sse --port 8000
+```
+
+### Python
+
+```python
+from mcp_gitlab.servers.gitlab import mcp
+
+# Run with stdio
+mcp.run()
+```
+
+## Tools (65)
+
+### Projects (4)
+| Tool | Description |
+|------|-------------|
+| `gitlab_get_project` | Get project details |
+| `gitlab_create_project` | Create a new project |
+| `gitlab_delete_project` | Delete a project |
+| `gitlab_update_project_merge_settings` | Update merge settings |
+
+### Project Approvals (8)
+| Tool | Description |
+|------|-------------|
+| `gitlab_get_project_approvals` | Get approval config |
+| `gitlab_update_project_approvals` | Update approval settings |
+| `gitlab_list_project_approval_rules` | List approval rules |
+| `gitlab_create_project_approval_rule` | Create approval rule |
+| `gitlab_update_project_approval_rule` | Update approval rule |
+| `gitlab_delete_project_approval_rule` | Delete approval rule |
+| `gitlab_list_mr_approval_rules` | List MR approval rules |
+| `gitlab_create_mr_approval_rule` | Create MR approval rule |
+| `gitlab_update_mr_approval_rule` | Update MR approval rule |
+| `gitlab_delete_mr_approval_rule` | Delete MR approval rule |
+
+### Groups (6)
+| Tool | Description |
+|------|-------------|
+| `gitlab_list_groups` | List groups |
+| `gitlab_get_group` | Get group details |
+| `gitlab_share_project_with_group` | Share project with group |
+| `gitlab_unshare_project_with_group` | Unshare project from group |
+| `gitlab_share_group_with_group` | Share group with group |
+| `gitlab_unshare_group_with_group` | Unshare group from group |
+
+### Branches (3)
+| Tool | Description |
+|------|-------------|
+| `gitlab_list_branches` | List branches |
+| `gitlab_create_branch` | Create a branch |
+| `gitlab_delete_branch` | Delete a branch |
+
+### Commits (4)
+| Tool | Description |
+|------|-------------|
+| `gitlab_list_commits` | List commits |
+| `gitlab_get_commit` | Get commit (with optional diff) |
+| `gitlab_create_commit` | Create commit with file actions |
+| `gitlab_compare` | Compare branches/tags/commits |
+
+### Merge Requests (9)
+| Tool | Description |
+|------|-------------|
+| `gitlab_list_mrs` | List merge requests |
+| `gitlab_get_mr` | Get MR details |
+| `gitlab_create_mr` | Create merge request |
+| `gitlab_update_mr` | Update merge request |
+| `gitlab_merge_mr` | Merge a merge request |
+| `gitlab_merge_mr_sequence` | Merge multiple MRs in order |
+| `gitlab_rebase_mr` | Rebase a merge request |
+| `gitlab_mr_changes` | Get MR file changes |
+
+### MR Notes (6)
+| Tool | Description |
+|------|-------------|
+| `gitlab_list_mr_notes` | List MR comments |
+| `gitlab_add_mr_note` | Add comment to MR |
+| `gitlab_delete_mr_note` | Delete MR comment |
+| `gitlab_update_mr_note` | Update MR comment |
+| `gitlab_award_emoji` | Award emoji to note |
+| `gitlab_remove_emoji` | Remove emoji from note |
+
+### MR Discussions (4)
+| Tool | Description |
+|------|-------------|
+| `gitlab_list_mr_discussions` | List discussions |
+| `gitlab_create_mr_discussion` | Create discussion (inline + multi-line) |
+| `gitlab_reply_to_discussion` | Reply to discussion |
+| `gitlab_resolve_discussion` | Resolve/unresolve discussion |
+
+### Pipelines (5)
+| Tool | Description |
+|------|-------------|
+| `gitlab_list_pipelines` | List pipelines |
+| `gitlab_get_pipeline` | Get pipeline (with optional jobs) |
+| `gitlab_create_pipeline` | Trigger pipeline |
+| `gitlab_retry_pipeline` | Retry failed jobs |
+| `gitlab_cancel_pipeline` | Cancel pipeline |
+
+### Jobs (4)
+| Tool | Description |
+|------|-------------|
+| `gitlab_retry_job` | Retry a job |
+| `gitlab_play_job` | Trigger manual job |
+| `gitlab_cancel_job` | Cancel a job |
+| `gitlab_get_job_log` | Get job log output |
+
+### Tags (4)
+| Tool | Description |
+|------|-------------|
+| `gitlab_list_tags` | List tags |
+| `gitlab_get_tag` | Get tag details |
+| `gitlab_create_tag` | Create a tag |
+| `gitlab_delete_tag` | Delete a tag |
+
+### Releases (5)
+| Tool | Description |
+|------|-------------|
+| `gitlab_list_releases` | List releases |
+| `gitlab_get_release` | Get release details |
+| `gitlab_create_release` | Create a release |
+| `gitlab_update_release` | Update a release |
+| `gitlab_delete_release` | Delete a release |
+
+### CI/CD Variables (8)
+| Tool | Description |
+|------|-------------|
+| `gitlab_list_variables` | List project variables |
+| `gitlab_create_variable` | Create project variable |
+| `gitlab_update_variable` | Update project variable |
+| `gitlab_delete_variable` | Delete project variable |
+| `gitlab_list_group_variables` | List group variables |
+| `gitlab_create_group_variable` | Create group variable |
+| `gitlab_update_group_variable` | Update group variable |
+| `gitlab_delete_group_variable` | Delete group variable |
+
+### Issues (5)
+| Tool | Description |
+|------|-------------|
+| `gitlab_list_issues` | List issues |
+| `gitlab_get_issue` | Get issue details |
+| `gitlab_create_issue` | Create an issue |
+| `gitlab_update_issue` | Update an issue |
+| `gitlab_add_issue_comment` | Add comment to issue |
+
+## Development
+
+```bash
+# Clone and install
+git clone https://github.com/vish288/mcp-gitlab.git
+cd mcp-gitlab
+uv sync --all-extras
+
+# Run tests
+uv run pytest --cov
+
+# Lint
+uv run ruff check .
+uv run ruff format --check .
+```
+
+## License
+
+MIT