Skip to main content
Glama
jmrplens

Gitlab MCP Server

by jmrplens
OverviewSchemaRelated ServersScoreDiscussions
Go
Hybrid

Environment

gitlab_environment
Destructive

Create, update, and stop GitLab environments; protect environments with deploy access rules; manage freeze periods to block deploys; and audit deployment records including approval workflow.

Instructions

Example: {"action":"create","params":{...}} For the params schema of any action, read the MCP resource gitlab://schema/meta/gitlab_environment/.

Manage GitLab deployment environments, protected environments, freeze (deploy block) periods, and the deployment record audit trail. Delete and stop are destructive (stop terminates the running env; force=true skips on-stop jobs). When to use: define/update environments (production, staging, review/*), restrict who can deploy via protected environments, schedule deploy freezes, audit deployment history, approve/reject deployments awaiting manual gate. NOT for: CI/CD variables scoped to environments (use gitlab_ci_variable), pipelines/jobs (use gitlab_pipeline / gitlab_job), feature flag rollout strategies (use gitlab_feature_flags).

Behavior:

  • Idempotent reads: list / get / protected_list / protected_get / freeze_list / freeze_get / deployment_list / deployment_get / deployment_merge_requests.

  • update / protected_update / freeze_update / deployment_update are idempotent (same input → same state). create / protected_protect / freeze_create / deployment_create are NON-idempotent on duplicate (project_id, name) — return 409. deployment_approve_or_reject is single-shot per (deployment_id, user) and cannot be reversed.

  • Side effects: stop runs the on-stop CI job (unless force=true) and terminates any review-app resources; deployment_approve_or_reject may release queued CI jobs awaiting a manual gate; freeze_create immediately blocks deploys that match the cron window.

  • Destructive: delete and stop are destructive — stop cannot be reversed without re-deploying; deployment_delete removes the deployment audit record (history loss).

Returns: resource object (environment / protection / freeze / deployment) for _get/_create/_update/_protect; paginated array for *_list; updated deployment with approval state for deployment_approve_or_reject; MR list for deployment_merge_requests; {success, message} for _delete/_unprotect/stop. Errors: 404 not found, 403 forbidden (hint: protect/unprotect require Maintainer+), 400 invalid params (hint: tier ∈ production/staging/testing/development/other; freeze cron timezone must be valid TZ name).

Param conventions: * = required. All actions need project_id*. environment_id is the numeric ID returned by list/create.

Environments:

  • list: project_id*, name, search, states (available/stopped/stopping), page, per_page

  • get / delete: project_id*, environment_id*

  • create: project_id*, name*, description, external_url, tier (production/staging/testing/development/other)

  • update: project_id*, environment_id*, name, description, external_url, tier

  • stop: project_id*, environment_id*, force (bool) — force skips on-stop jobs

Protected environments:

  • protected_list: project_id*, page, per_page

  • protected_get / protected_unprotect: project_id*, name*

  • protected_protect / protected_update: project_id*, name*, deploy_access_levels, approval_rules

Freeze periods (cron expressions):

  • freeze_list: project_id*, page, per_page

  • freeze_get / freeze_delete: project_id*, freeze_period_id*

  • freeze_create: project_id*, freeze_start* (cron, e.g. '0 23 * * 5'), freeze_end* (cron), cron_timezone

  • freeze_update: project_id*, freeze_period_id*, freeze_start, freeze_end, cron_timezone

Deployments (immutable history records):

  • deployment_list: project_id*, order_by, sort, environment, status, page, per_page

  • deployment_get / deployment_delete: project_id*, deployment_id*

  • deployment_create: project_id*, environment*, ref*, sha*, tag (bool), status (created/running/success/failed/canceled)

  • deployment_update: project_id*, deployment_id*, status*

  • deployment_approve_or_reject: project_id*, deployment_id*, status* (approved/rejected), comment

  • deployment_merge_requests: project_id*, deployment_id*, state, order_by, sort, page, per_page

See also: gitlab_pipeline / gitlab_job (CI runs deploying to environments), gitlab_ci_variable (env-scoped variables), gitlab_feature_flags (env-scoped strategies).

Input Schema

TableJSON Schema
NameRequiredDescriptionDefault
actionYesAction to perform. Pick exactly one of the values in `enum`. Each action expects its own `params` object — see the tool description for the per-action parameter list.
paramsNoAction-specific parameters as a JSON object. Required and optional fields differ per action; consult this tool's description for the chosen action. Send only the fields documented for that action — unknown keys are rejected with a validation error (only reserved meta keys like `confirm` are stripped before validation). For the JSON Schema of a specific action's `params`, read the MCP resource `gitlab://schema/meta/{tool}/{action}` (replace placeholders with the tool name and the chosen action).

Output Schema

TableJSON Schema
NameRequiredDescriptionDefault
next_stepsNoOptional. Suggested follow-up actions or tool calls for the LLM, contextual to the result.
paginationNoPresent on list actions. Use `has_more` and `next_page` to paginate through results.

Tool Definition Quality

A5/5.0
Behavior5/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

The description provides extensive behavioral details beyond the annotations. It explains idempotency for each action, side effects (e.g., stop triggers on-stop jobs, deployment_approve_or_reject releases CI gates), destructive actions (delete, stop, deployment_delete), error types, and authorization hints (e.g., protect/unprotect require Maintainer+). This fully compensates for the annotations' brevity.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is long but well-organized: it starts with an example, then covers purpose, when/not, behavior, returns, errors, param conventions, and detailed per-action parameters. Every section serves a purpose, and the information is front-loaded with the most critical details (example, purpose).

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness5/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given the tool's 23 actions and complex side effects, the description covers all necessary aspects: return types, error handling, idempotency, destructive effects, param conventions, and even references an MCP resource for detailed schema. The output schema exists, but the description still provides useful return summaries. No gaps remain.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters5/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Although the input schema only has two top-level fields (action and params), the description lists all per-action parameters with their requirements and hints (e.g., project_id*, environment_id*). This adds significant meaning beyond the schema, which only provides a generic description for params.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states that the tool manages GitLab deployment environments, protected environments, freeze periods, and deployment audit trail. It explicitly lists what actions are covered and distinguishes itself from sibling tools like gitlab_ci_variable, gitlab_pipeline, etc., ensuring the agent knows exactly what this tool handles.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines5/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description provides explicit guidance on when to use the tool (e.g., define/update environments, restrict deploys, schedule freezes) and when not to use it (not for CI/CD variables, pipelines, feature flags). It also references sibling tools for alternatives, making the usage context very clear.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Install Server

Other Tools

Latest Blog Posts

MCP directory API

We provide all the information about MCP servers via our MCP API.

curl -X GET 'https://glama.ai/api/mcp/v1/servers/jmrplens/gitlab-mcp-server'

If you have feedback or need assistance with the MCP directory API, please join our Discord server