{
  "markdown": "# MCP GitLab CrunchTools\n\nA secure MCP (Model Context Protocol) server for GitLab projects, merge requests, issues, pipelines, and search. Works with any GitLab instance (gitlab.com, self-hosted, or enterprise).\n\n## Overview\n\nThis MCP server is designed to be:\n\n- **Secure by default** - Comprehensive threat modeling, input validation, and token protection\n- **No third-party services** - Runs locally via stdio, your API token never leaves your machine\n- **Multi-instance** - Works with gitlab.com, self-hosted GitLab, or enterprise instances via configurable URL\n- **Cross-platform** - Works on Linux, macOS, and Windows\n- **Automatically updated** - GitHub Actions monitor for CVEs and update dependencies\n- **Containerized** - Available at `quay.io/crunchtools/mcp-gitlab` built on [Hummingbird Python](https://quay.io/repository/hummingbird/python) base image\n\n## Naming Convention\n\n| Component | Name |\n|-----------|------|\n| GitHub repo | [crunchtools/mcp-gitlab](https://github.com/crunchtools/mcp-gitlab) |\n| Container | `quay.io/crunchtools/mcp-gitlab` |\n| Python package (PyPI) | `mcp-gitlab-crunchtools` |\n| CLI command | `mcp-gitlab-crunchtools` |\n| Module import | `mcp_gitlab_crunchtools` |\n\n## Why Hummingbird?\n\nThe container image is built on the [Hummingbird Python base image](https://quay.io/repository/hummingbird/python) from [Project Hummingbird](https://github.com/hummingbird-project), which provides:\n\n- **Minimal CVE exposure** - Built with a minimal package set, dramatically reducing the attack surface\n- **Regular updates** - Security patches are applied promptly\n- **Optimized for Python** - Pre-configured Python environment with uv package manager\n- **Production-ready** - Proper signal handling and non-root user defaults\n\n## Features\n\n### Project Management (5 tools)\n- `list_projects` - List projects with filtering and search\n- `get_project` - Get project details by ID or path\n- `list_project_branches` - List repository branches\n- `get_project_branch` - Get a single branch\n- `list_project_commits` - List commits with date/path filtering\n\n### Group Management (3 tools)\n- `list_groups` - List groups with filtering\n- `get_group` - Get group details by ID or path\n- `list_group_projects` - List projects in a group (with subgroup support)\n\n### Merge Requests (7 tools)\n- `list_merge_requests` - List MRs by state, labels, milestone\n- `get_merge_request` - Get MR details\n- `create_merge_request` - Create a new MR\n- `update_merge_request` - Update MR title, description, state, assignees\n- `list_mr_notes` - List comments on an MR\n- `create_mr_note` - Add a comment to an MR\n- `get_mr_changes` - Get the diff for an MR\n\n### Issues (6 tools)\n- `list_issues` - List issues by state, labels, milestone, assignee\n- `get_issue` - Get issue details\n- `create_issue` - Create a new issue\n- `update_issue` - Update issue title, description, state, labels\n- `list_issue_notes` - List comments on an issue\n- `create_issue_note` - Add a comment to an issue\n\n### Pipelines (4 tools)\n- `list_pipelines` - List CI/CD pipelines with status filtering\n- `get_pipeline` - Get pipeline details\n- `list_pipeline_jobs` - List jobs in a pipeline\n- `get_job_log` - Get job log output\n\n### Search (2 tools)\n- `search_global` - Search across all accessible GitLab resources\n- `search_project` - Search within a specific project\n\n## Installation\n\n### With uvx (Recommended)\n\n```bash\nuvx mcp-gitlab-crunchtools\n```\n\n### With pip\n\n```bash\npip install mcp-gitlab-crunchtools\n```\n\n### With Container\n\n```bash\npodman run -e GITLAB_TOKEN=your_token \\\n    quay.io/crunchtools/mcp-gitlab\n```\n\n## Configuration\n\n### Environment Variables\n\n| Variable | Required | Default | Description |\n|----------|----------|---------|-------------|\n| `GITLAB_TOKEN` | Yes | — | Personal Access Token |\n| `GITLAB_URL` | No | `https://gitlab.com` | GitLab instance URL |\n\n### Creating a GitLab Personal Access Token\n\n1. **Navigate to Access Tokens**\n   - Go to https://gitlab.com/-/user_settings/personal_access_tokens\n   - Or: Avatar > Preferences > Access Tokens\n\n2. **Create a Custom Token**\n   - **Name**: `mcp-gitlab-crunchtools`\n   - **Expiration**: Set an appropriate date (90 days recommended)\n   - **Scopes**: Select scopes based on your needs\n\n3. **Scope Selection**\n\n   | Scope | Access Level | Capabilities |\n   |-------|-------------|--------------|\n   | `read_api` | Read-only | List/view projects, issues, MRs, pipelines |\n   | `api` | Full access | All features including create/update |\n\n4. **Copy and Store Token**\n   - Copy the token immediately (starts with `glpat-`)\n   - Store securely in a password manager\n\n### Add to Claude Code\n\n```bash\nclaude mcp add mcp-gitlab-crunchtools \\\n    --env GITLAB_TOKEN=your_token_here \\\n    -- uvx mcp-gitlab-crunchtools\n```\n\nFor self-hosted GitLab:\n\n```bash\nclaude mcp add mcp-gitlab-crunchtools \\\n    --env GITLAB_TOKEN=your_token_here \\\n    --env GITLAB_URL=https://gitlab.example.com \\\n    -- uvx mcp-gitlab-crunchtools\n```\n\nFor the container version:\n\n```bash\nclaude mcp add mcp-gitlab-crunchtools \\\n    --env GITLAB_TOKEN=your_token_here \\\n    -- podman run -i --rm -e GITLAB_TOKEN quay.io/crunchtools/mcp-gitlab\n```\n\n## Usage Examples\n\n### List Your Projects\n\n```\nUser: List my GitLab projects\nAssistant: [calls list_projects with membership=true]\n```\n\n### View Merge Requests\n\n```\nUser: Show open merge requests for my-org/backend\nAssistant: [calls list_merge_requests with project_id=\"my-org/backend\"]\n```\n\n### Create an Issue\n\n```\nUser: Create an issue in my-org/backend titled \"Fix login timeout\"\nAssistant: [calls create_issue with title=\"Fix login timeout\"]\n```\n\n### Check Pipeline Status\n\n```\nUser: Show failed pipelines for my-org/api\nAssistant: [calls list_pipelines with status=\"failed\"]\n```\n\n### Search Code\n\n```\nUser: Search for \"authentication\" in my-org/backend\nAssistant: [calls search_project with scope=\"blobs\"]\n```\n\n## Security\n\nThis server was designed with security as a primary concern. See [SECURITY.md](SECURITY.md) for:\n\n- Threat model and attack vectors\n- Defense in depth architecture\n- Token handling best practices\n- Input validation rules\n- Audit logging\n\n### Key Security Features\n\n1. **Token Protection**\n   - Stored as SecretStr (never accidentally logged)\n   - Environment variable only (never in files or args)\n   - Sanitized from all error messages\n\n2. **Input Validation**\n   - Pydantic models for all inputs\n   - Allowlist character validation for project/group IDs\n   - Path traversal prevention\n\n3. **API Hardening**\n   - HTTPS enforcement (except localhost)\n   - TLS certificate validation\n   - Request timeouts (30s)\n   - Response size limits (10MB)\n\n4. **Automated CVE Scanning**\n   - GitHub Actions scan dependencies weekly\n   - Container security scanning with Trivy\n   - CodeQL analysis for Python\n\n## Development\n\n### Setup\n\n```bash\ngit clone https://github.com/crunchtools/mcp-gitlab.git\ncd mcp-gitlab\nuv sync\n```\n\n### Run Tests\n\n```bash\nuv run pytest\n```\n\n### Lint and Type Check\n\n```bash\nuv run ruff check src tests\nuv run mypy src\n```\n\n### Build Container\n\n```bash\npodman build -t mcp-gitlab .\n```\n\n## License\n\nAGPL-3.0-or-later\n\n## Contributing\n\nContributions welcome! Please read SECURITY.md before submitting security-related changes.\n\n## Links\n\n- [GitLab REST API Documentation](https://docs.gitlab.com/ee/api/rest/)\n- [FastMCP Documentation](https://gofastmcp.com/)\n- [MCP Specification](https://modelcontextprotocol.io/)\n- [crunchtools.com](https://crunchtools.com)\n\n<!-- mcp-name: io.github.crunchtools/gitlab -->\n",
  "bytes": 7524,
  "sha": "5617a4474d968b5e7b1637462d051c2ed1d997bb6c47150cd275440569fbdcde",
  "repo_slug": "crunchtools/mcp-gitlab",
  "fonte": "repo",
  "truncated": false,
  "api": "https://agentalog.com/api/listings/mcp_io_github_crunchtools_gitlab_8d1735fc/readme"
}