CERN GitLab CLI

A command-line interface and MCP server for interacting with CERN GitLab (gitlab.cern.ch). Provides 15 tools for searching, browsing, and analyzing HEP code repositories.

The CLI binary is cerngitlab-cli. All commands return structured JSON. Public repositories work without authentication; private/internal repos and code search require a token.

MCP Server

The same 15 tools are exposed over the Model Context Protocol using the MCP Python SDK v2 (protocol revision 2026-07-28). Older clients that use the legacy initialize handshake (2025-11-25 and earlier) remain supported through automatic protocol negotiation.

Two entry points are installed:

Or use cerngitlab-mcp --mode auto|stdio|http (auto-detects from CERNGITLAB_HOST/CERNGITLAB_PORT).

Connecting from an MCP client

stdio — register the command directly:

{
  "mcpServers": {
    "cern-gitlab": {
      "command": "cerngitlab-mcp-stdio",
      "env": { "CERNGITLAB_TOKEN": "glpat-xxxxxxxxxxxx" }
    }
  }
}

HTTP — point the client at http://<host>:<port>/mcp. Requests must carry a CERN SSO bearer token in the Authorization: Bearer <token> header. The endpoint speaks Streamable HTTP in stateless mode. Deploy a single worker because pending OAuth state/PKCE verifiers are stored in process memory. Authorize GitLab separately through /oauth/authorize before connecting.

Protocol capabilities

• All tools advertise readOnlyHint: true, destructiveHint: false,

idempotentHint: true, and openWorldHint: true (they access external GitLab).

• Every tool declares an output schema and returns structured content.
• GitLab errors and invalid tool arguments return actionable isError: true

results so agents can correct their calls. Malformed protocol requests remain JSON-RPC errors.

• Tool discovery has a stable order and a five-minute private cache hint.
• Stdio startup performs no network probes; use test_connectivity on demand.
• get_file_content accepts optional 1-based, inclusive start_line/end_line.

For Claude Code, Codex, and remote authentication examples, see MCP client integration and the client configuration templates.

Configuration

Set environment variables prefixed with CERNGITLAB_:

To create a token: visit https://gitlab.cern.ch/-/user_settings/personal_access_tokens, create with read_api scope, then export CERNGITLAB_TOKEN=glpat-xxxxxxxxxxxx.

Authentication

Most tools work without authentication for public repositories. However, some features require a personal access token:

Tools that require authentication:

• search-code — Global code search across all repositories
• search-lhcb-stack — Code search within LHCb software stacks
• get-wiki — Access to project wiki pages

Tools that may require authentication:

• list-releases — Some projects restrict release API access
• get-release — Some projects restrict release API access

Getting a Token

1. Visit: https://gitlab.cern.ch/-/user_settings/personal_access_tokens
2. Create a new token with the read_api scope
3. Export it: export CERNGITLAB_TOKEN=glpat-xxxxxxxxxxxx

Checking Auth Status

Use test-connection to verify your authentication status:

cerngitlab-cli test-connection

Returns:

{
  "status": "connected",
  "authenticated": false,
  "note": "No token provided — public access only"
}

With a token:

{
  "status": "connected",
  "authenticated": true,
  "user": "username"
}

Tool Selection Guide

*\ Note:** Some projects may restrict release/tag API access. If you get a 403 error, set CERNGITLAB_TOKEN.

Common Workflows

Discover repositories

# Find Python ROOT analysis projects, sorted by stars
cerngitlab-cli search-projects --query "ROOT analysis" --language python --sort-by stars

# Find all LHCb-tagged repositories
cerngitlab-cli search-projects --topic lhcb --per-page 50

Understand a project

# Get README, file tree, and full project inspection in sequence
cerngitlab-cli get-readme --project lhcb/DaVinci
cerngitlab-cli list-files --project lhcb/DaVinci --path src/
cerngitlab-cli inspect-project --project lhcb/DaVinci

Work on a non-default branch

cerngitlab-cli list-branches --project lhcb/DaVinci --search release
cerngitlab-cli list-files --project lhcb/DaVinci --ref release/v2
cerngitlab-cli search-code --project lhcb/DaVinci --ref release/v2 --search-term Scheduler

inspect-project is the most powerful single command — it analyzes build systems, dependencies, CI/CD config, and language breakdown in one call.

Find code patterns

# Global code search (requires token)
cerngitlab-cli search-code --search-term "RooFit" --per-page 10

# Search within a specific project
cerngitlab-cli search-code --search-term "PVFinder" --project lhcb/allen

# Search within an LHCb software stack (auto-resolves correct git refs)
cerngitlab-cli search-lhcb-stack --search-term "initialize()" --stack sim11

Track releases and tags

cerngitlab-cli list-releases --project lhcb/DaVinci
cerngitlab-cli get-release --project lhcb/DaVinci --tag-name v1.2.0
cerngitlab-cli list-tags --project lhcb/DaVinci --search v1

Error Handling

All commands return JSON errors: {"error": "Error message"}. Common causes:

• "Authentication required" / "Search API requires authentication" / "Wiki access denied": Tool needs CERNGITLAB_TOKEN but none is set. Set the environment variable with a personal access token (read_api scope).
• "Project not found" / "<project_path> not found": Wrong project ID or path — verify with search-projects. Note: some tools work better with numeric project IDs than group/project paths.
• "GitLab API error (403): 403 Forbidden": API access restricted for this project. May require authentication or project is private.
• "Rate limit exceeded": Wait and retry (default: 300 req/min).
• "File not found": Check --ref branch and verify path with list-files.

Tool Reference

1. search-projects

Search for public CERN GitLab projects by keywords, topics, or programming language.

Parameters:

Output: Array of project objects:

{
  "id": 12345,
  "name": "ProjectName",
  "path_with_namespace": "group/project",
  "description": "...",
  "web_url": "https://gitlab.cern.ch/group/project",
  "default_branch": "main",
  "topics": ["physics", "root"],
  "star_count": 42,
  "forks_count": 15,
  "last_activity_at": "2025-03-10T10:30:00Z",
  "created_at": "2020-01-15T08:00:00Z",
  "visibility": "public"
}

2. get-project-info

Get detailed metadata about a specific project including languages, statistics, and license.

Parameters:

Output: Single project object with all fields from search-projects plus:

{
  "languages": ["Python", "C++"],
  "language_percentages": {"Python": 60.5, "C++": 39.5},
  "open_issues_count": 23,
  "license": "MIT"
}

3. list-files

List files and directories in a project's repository.

Parameters:

Output: Array of entries:

{"type": "tree", "path": "src", "name": "src"}
{"type": "blob", "path": "README.md", "name": "README.md"}

Tip: If you get a "not found" error with a group/project path, try using the numeric project ID instead (found via search-projects or get-project-info).

4. get-file

Retrieve the content of a specific file from a repository.

Parameters:

Output:

{
  "file_name": "main.py",
  "file_path": "src/main.py",
  "size": 1234,
  "ref": "main",
  "last_commit_id": "abc123...",
  "content_sha256": "sha256hash...",
  "is_binary": false,
  "content": "#!/usr/bin/env python\n...",
  "language": "python"
}

Binary files return "is_binary": true and "content": "[Binary file, N bytes]".

5. get-readme

Get the README content for a project. Automatically finds README.md, .rst, .txt, etc.

Parameters:

Output:

{
  "file_name": "README.md",
  "content": "# Project Title\n\nDescription...",
  "language": "markdown"
}

6. search-code

Search for code snippets across repositories. Returns matching files with line-level context. Requires authentication for global search on CERN GitLab.

Parameters:

Output:

{
  "search_term": "RooFit",
  "scope": "blobs",
  "project": "(global)",
  "page": 1,
  "per_page": 20,
  "total_results": 15,
  "results": [
    {
      "file_name": "fitting.py",
      "file_path": "src/analysis/fitting.py",
      "project_id": 12345,
      "data": "import ROOT\nfrom ROOT import RooFit\n...",
      "ref": "main",
      "startline": 10
    }
  ]
}

7. search-lhcb-stack

Search for code within a specific LHCb software stack (e.g., sim11). Automatically resolves correct Git references using the LHCb nightly build API.

Parameters:

Output: Same format as search-code, with automatically resolved branch references.

8. search-issues

Search for issues and discussions in a project.

Parameters:

Output:

[
  {
    "id": 123,
    "iid": 45,
    "project_id": 67890,
    "title": "Issue title",
    "description": "Issue description...",
    "state": "opened",
    "created_at": "2025-01-10T09:00:00Z",
    "updated_at": "2025-03-05T14:30:00Z",
    "web_url": "https://gitlab.cern.ch/group/project/-/issues/45"
  }
]

9. get-wiki

Access project wiki pages. Requires authentication.

Parameters:

Output (list mode):

[{"slug": "home", "title": "Home", "url": "https://gitlab.cern.ch/group/project/-/wikis/home"}]

Output (specific page):

{"slug": "installation", "title": "Installation Guide", "content": "# Installation\n\nSteps..."}

10. inspect-project

Comprehensive analysis of a project's structure, build system, dependencies, and CI/CD configuration. This is the most informative single command for understanding a project.

Parameters:

Output:

{
  "project": "lhcb/allen",
  "ref": "main",
  "ecosystems": ["python", "cpp"],
  "build_systems": ["cmake", "python-build"],
  "dependencies": [
    {
      "source_file": "requirements.txt",
      "ecosystem": "python",
      "count": 15,
      "items": [
        {"name": "numpy", "version_spec": ">=1.20"},
        {"name": "scipy", "version_spec": ""}
      ]
    }
  ],
  "ci_config": {
    "found": true,
    "analysis": {
      "stages": ["build", "test", "deploy"],
      "jobs": ["build_linux", "test_unit", "deploy_prod"],
      "image": "python:3.11"
    },
    "raw_preview": "stages:\n  - build\n  - test..."
  },
  "files_analyzed": 8
}

11. list-releases

List releases for a project.

Parameters:

Output:

[
  {
    "tag_name": "v1.2.0",
    "name": "Release 1.2.0",
    "description": "Release notes...",
    "created_at": "2025-02-15T10:00:00Z",
    "published_at": "2025-02-15T12:00:00Z",
    "web_url": "https://gitlab.cern.ch/group/project/-/releases/v1.2.0"
  }
]

12. get-release

Get detailed information about a specific release.

Parameters:

Output: Same as list-releases entry, plus assets array:

{"assets": [{"name": "source.tar.gz", "url": "..."}]}

13. list-tags

List project tags with optional filtering.

Parameters:

Output:

[
  {
    "name": "v1.2.0",
    "message": "Release 1.2.0",
    "target": "main",
    "commit": {
      "id": "abc123...",
      "short_id": "abc123",
      "created_at": "2025-02-15T10:00:00Z"
    }
  }
]

14. list-branches

List or search repository branches. A returned branch name can be passed to the --ref option of repository content, code search, and inspection commands.

Parameters:

Example:

cerngitlab-cli list-branches --project lhcb/DaVinci --search release

15. test-connection

Test connectivity to the CERN GitLab instance. Takes no parameters.

Output:

{
  "status": "connected",
  "gitlab_url": "https://gitlab.cern.ch",
  "authenticated": true,
  "version": "16.0.0",
  "revision": "abc123",
  "public_access": true
}