gitlab-api 26.0.1

GitLab API + MCP Server + A2A Server

Gitlab Api

CLI or API | MCP | Agent

Version: 26.0.1

Documentation — Installation, deployment, usage across the API, CLI, and MCP interfaces, the integrated A2A agent server, and guidance for provisioning the backing GitLab instance are maintained in the official documentation.

---

Overview

Gitlab Api is a production-grade Agent and Model Context Protocol (MCP) server designed to interface directly with GitLab API + MCP Server + A2A Server.

---

Key Features

• Consolidated Action-Routed MCP Tools: Minimizes token overhead and eliminates tool bloat in LLM contexts by grouping methods into optimized, togglable tool modules.
• Enterprise-Grade Security: Comprehensive support for Eunomia policies, OIDC token delegation, and granular execution context tracking.
• Integrated Graph Agent: Built-in Pydantic AI agent supporting the Agent Control Protocol (ACP) and standard Web interfaces (AG-UI).
• Native Telemetry & Tracing: Out-of-the-box OpenTelemetry exports and native Langfuse tracing.

---

CLI or API

This agent wraps the GitLab API + MCP Server + A2A Server API. You can interact with it programmatically or via its integrated execution entrypoints.

Detailed instructions on how to use the underlying API wrappers, extended schema bindings, and developer SDK references are maintained in docs/index.md.

---

MCP

This server utilizes dynamic Action-Routed tools to optimize token overhead and maximize IDE compatibility.

Tool surface — MCP_TOOL_MODE

Set MCP_TOOL_MODE (in the shared ~/.config/agent-utilities/config.json or env): condensed (default — the action-routed tools below), verbose (one named 1:1 tool per API method, e.g. gitlab_get_branches(...), tagged verbose), or both. Filter the verbose set with --tools tag:verbose / MCP_ENABLED_TAGS=verbose. See the agent-utilities MCP Tool Modes guide.

Available MCP Tools

Auto-generated from the live MCP server — do not edit by hand.

Condensed action-routed tools (default — MCP_TOOL_MODE=condensed)

MCP Tool	Toggle Env Var	Description
api_request	CUSTOM_APITOOL	Execute arbitrary GitLab REST API requests directly.
gitlab_branches	BRANCHESTOOL	Manage gitlab branches operations.
gitlab_commits	COMMITSTOOL	Manage gitlab commits operations.
gitlab_deploy_tokens	DEPLOY_TOKENSTOOL	Manage gitlab deploy tokens operations.
gitlab_discover_graphql_schema	GRAPHQLTOOL	Discover the dynamic GitLab GraphQL schema including types, fields, and custom attributes in real-time.
gitlab_environments	ENVIRONMENTSTOOL	Manage gitlab environments operations.
gitlab_epics	EPICSTOOL	Manage GitLab epics.
gitlab_graphql	GRAPHQLTOOL	Execute raw GraphQL queries and mutations natively on GitLab.
gitlab_groups	GROUPSTOOL	Manage gitlab groups operations.
gitlab_instances	MISCTOOL	List the configured GitLab tenants (CONCEPT:KG-2.9g).
gitlab_issues	ISSUESTOOL	Manage GitLab issues.
gitlab_jobs	JOBSTOOL	Manage gitlab jobs operations.
gitlab_labels	LABELSTOOL	Manage GitLab labels.
gitlab_members	MEMBERSTOOL	Manage gitlab members operations.
gitlab_merge_requests	MERGE_REQUESTSTOOL	Manage gitlab merge requests operations.
gitlab_merge_rules	MERGE_RULESTOOL	Manage gitlab merge rules operations.
gitlab_milestones	MILESTONESTOOL	Manage GitLab milestones.
gitlab_notes	NOTESTOOL	Manage GitLab notes/comments on issues, merge requests, commits, and epics.
gitlab_packages	PACKAGESTOOL	Manage gitlab packages operations.
gitlab_pipeline_schedules	PIPELINE_SCHEDULESTOOL	Manage gitlab pipeline schedules operations.
gitlab_pipelines	PIPELINESTOOL	Manage gitlab pipelines operations.
gitlab_projects	PROJECTSTOOL	Manage gitlab projects operations.
gitlab_protected_branches	PROTECTED_BRANCHESTOOL	Manage gitlab protected branches operations.
gitlab_releases	RELEASESTOOL	Manage gitlab releases operations.
gitlab_runners	RUNNERSTOOL	Manage gitlab runners operations.
gitlab_snippets	SNIPPETSTOOL	Manage GitLab snippets.
gitlab_tags	TAGSTOOL	Manage gitlab tags operations.

Verbose 1:1 API-mapped tools (MCP_TOOL_MODE=verbose or both)

188 per-operation tools — one per public API method (click to expand)

MCP Tool	Toggle Env Var	Description
gitlab_api_request	SYSTEMTOOL	Make a custom API request to the GitLab server.
gitlab_approve_merge_request	MERGE_REQUESTSTOOL	Approve a specific merge request.
gitlab_archive_project	PROJECTSTOOL	Archive a specific project.
gitlab_cancel_project_job	PROJECTSTOOL	Cancel a specific job within a project.
gitlab_cherry_pick_commit	REPOSITORIESTOOL	Cherry-pick a commit into a new branch.
gitlab_create_branch	REPOSITORIESTOOL	Create a new branch in a project.
gitlab_create_commit	REPOSITORIESTOOL	Create a new commit.
gitlab_create_commit_comment	REPOSITORIESTOOL	Create a comment on a commit.
gitlab_create_environment	ENVIRONMENTSTOOL	Create a new environment for a project.
gitlab_create_epic	ISSUESTOOL	Create a new group epic.
gitlab_create_group_deploy_token	USERS_GROUPSTOOL	Create a deploy token for a group.
gitlab_create_issue	ISSUESTOOL	Create a new issue.
gitlab_create_label	ISSUESTOOL	Create a new label.
gitlab_create_merge_request	MERGE_REQUESTSTOOL	Create a new merge request.
gitlab_create_milestone	ISSUESTOOL	Create a project milestone.
gitlab_create_note	OTHERTOOL	Create a new note/comment on an issue.
gitlab_create_pipeline_schedule	PIPELINESTOOL	Create a pipeline schedule for a specific project.
gitlab_create_pipeline_schedule_variable	PIPELINESTOOL	Create a variable for a pipeline schedule.
gitlab_create_project_deploy_token	PROJECTSTOOL	Create a deploy token for a project.
gitlab_create_project_level_rule	PROJECTSTOOL	Create a new project-level merge request approval rule.
gitlab_create_release	ENVIRONMENTSTOOL	Create a new release in a project.
gitlab_create_release_evidence	ENVIRONMENTSTOOL	Create evidence for a release in a project.
gitlab_create_snippet	OTHERTOOL	Create a project snippet or personal snippet.
gitlab_create_tag	REPOSITORIESTOOL	Create a tag in a project.
gitlab_create_user	USERS_GROUPSTOOL	Create a new user.
gitlab_create_wiki_page	OTHERTOOL	Create a new wiki page for a project.
gitlab_delete_branch	REPOSITORIESTOOL	Delete a branch in a project.
gitlab_delete_environment	ENVIRONMENTSTOOL	Delete an environment for a project.
gitlab_delete_epic	ISSUESTOOL	Delete a group epic.
gitlab_delete_group_deploy_token	USERS_GROUPSTOOL	Delete a deploy token for a group.
gitlab_delete_issue	ISSUESTOOL	Delete an issue.
gitlab_delete_label	ISSUESTOOL	Delete a label.
gitlab_delete_merged_branches	REPOSITORIESTOOL	Delete all merged branches in a project.
gitlab_delete_milestone	ISSUESTOOL	Delete a project milestone.
gitlab_delete_note	OTHERTOOL	Delete a note.
gitlab_delete_pipeline_schedule	PIPELINESTOOL	Delete a pipeline schedule for a specific project.
gitlab_delete_pipeline_schedule_variable	PIPELINESTOOL	Delete a variable from a pipeline schedule.
gitlab_delete_project	PROJECTSTOOL	Delete a specific project.
gitlab_delete_project_deploy_token	PROJECTSTOOL	Delete a deploy token for a project.
gitlab_delete_project_level_rule	PROJECTSTOOL	Delete a project-level merge request approval rule.
gitlab_delete_project_runner	PROJECTSTOOL	Delete a runner from a project.
gitlab_delete_release	ENVIRONMENTSTOOL	Delete a release in a project.
gitlab_delete_runner	PIPELINESTOOL	Delete a runner.
gitlab_delete_shared_project_link	PROJECTSTOOL	Unshare a specific project from a group.
gitlab_delete_snippet	OTHERTOOL	Delete a snippet.
gitlab_delete_stopped_environments	ENVIRONMENTSTOOL	Delete stopped environments (review apps) for a project.
gitlab_delete_tag	REPOSITORIESTOOL	Delete a tag in a project.
gitlab_delete_user	USERS_GROUPSTOOL	Delete a user.
gitlab_delete_wiki_page	OTHERTOOL	Delete a wiki page for a project.
gitlab_download_release_asset	ENVIRONMENTSTOOL	Download a release asset from a group's release.
gitlab_download_repository_package	OTHERTOOL	Download a repository package for a specific project.
gitlab_edit_group	USERS_GROUPSTOOL	Edit a specific group.
gitlab_edit_group_level_rule	USERS_GROUPSTOOL	Edit a group-level merge request approval setting.
gitlab_edit_pipeline_schedule	PIPELINESTOOL	Edit a pipeline schedule for a specific project.
gitlab_edit_project	PROJECTSTOOL	Edit a specific project.
gitlab_edit_project_level_rule	PROJECTSTOOL	Edit a project-level merge request approval setting.
gitlab_enable_project_runner	PROJECTSTOOL	Enable a runner in a project.
gitlab_erase_project_job	PROJECTSTOOL	Erase a specific job within a project.
gitlab_get_approval_state_merge_requests	MERGE_REQUESTSTOOL	Get the approval state of merge requests for a specific project.
gitlab_get_branch	REPOSITORIESTOOL	Retrieve information about a specific branch in a project.
gitlab_get_branches	REPOSITORIESTOOL	Retrieve information about branches in a project.
gitlab_get_commit	REPOSITORIESTOOL	Get a specific commit.
gitlab_get_commit_comments	REPOSITORIESTOOL	Get comments on a commit.
gitlab_get_commit_diff	REPOSITORIESTOOL	Get the diff of a commit.
gitlab_get_commit_discussions	REPOSITORIESTOOL	Get discussions on a commit.
gitlab_get_commit_gpg_signature	REPOSITORIESTOOL	Get GPG signature of a commit.
gitlab_get_commit_merge_requests	REPOSITORIESTOOL	Get merge requests associated with a commit.
gitlab_get_commit_references	REPOSITORIESTOOL	Get references of a commit.
gitlab_get_commit_statuses	REPOSITORIESTOOL	Get statuses of a commit.
gitlab_get_commits	REPOSITORIESTOOL	Get commits.
gitlab_get_deploy_tokens	ENVIRONMENTSTOOL	Get all deploy tokens.
gitlab_get_environment	ENVIRONMENTSTOOL	Get details of a specific environment.
gitlab_get_environments	ENVIRONMENTSTOOL	Get a list of environments for a project.
gitlab_get_epic	ISSUESTOOL	Get a specific group epic.
gitlab_get_epics	ISSUESTOOL	Get all epics for a group.
gitlab_get_group	USERS_GROUPSTOOL	Get details of a specific group.
gitlab_get_group_deploy_token	USERS_GROUPSTOOL	Get a specific deploy token for a group.
gitlab_get_group_deploy_tokens	USERS_GROUPSTOOL	Get deploy tokens for a specific group.
gitlab_get_group_descendant_groups	USERS_GROUPSTOOL	Get descendant groups of a specific group.
gitlab_get_group_level_rule	USERS_GROUPSTOOL	Get details of a group-level merge request approval setting.
gitlab_get_group_members	USERS_GROUPSTOOL	Get members of a specific group.
gitlab_get_group_merge_requests	MERGE_REQUESTSTOOL	Get merge requests associated with a specific group.
gitlab_get_group_projects	PROJECTSTOOL	Get projects associated with a specific group.
gitlab_get_group_releases	USERS_GROUPSTOOL	Get information about releases in a group.
gitlab_get_group_runners	PIPELINESTOOL	Get information about runners in a group.
gitlab_get_group_subgroups	USERS_GROUPSTOOL	Get subgroups of a specific group.
gitlab_get_groups	USERS_GROUPSTOOL	Get a list of groups.
gitlab_get_issue	ISSUESTOOL	Get a single issue.
gitlab_get_issues	ISSUESTOOL	Get list of issues. Can filter by project_id.
gitlab_get_label	ISSUESTOOL	Get a specific label by name.
gitlab_get_labels	ISSUESTOOL	Get all labels for a project.
gitlab_get_latest_release	ENVIRONMENTSTOOL	Get information about the latest release in a project.
gitlab_get_latest_release_asset	ENVIRONMENTSTOOL	Get the asset for the latest release in a project.
gitlab_get_latest_release_evidence	ENVIRONMENTSTOOL	Get evidence for the latest release in a project.
gitlab_get_merge_request_level_rules	MERGE_REQUESTSTOOL	Get merge request-level approval rules for a specific project and merge request.
gitlab_get_merge_requests	MERGE_REQUESTSTOOL	Get a list of merge requests.
gitlab_get_milestone	ISSUESTOOL	Get a specific project milestone.
gitlab_get_milestones	ISSUESTOOL	Get all milestones for a project.
gitlab_get_namespace	USERS_GROUPSTOOL	Get information about a specific namespace.
gitlab_get_namespaces	USERS_GROUPSTOOL	Get information about namespaces.
gitlab_get_nested_projects_by_group	PROJECTSTOOL	Get information about nested projects within a group.
gitlab_get_note	OTHERTOOL	Get a specific note.
gitlab_get_notes	OTHERTOOL	Get all notes for a specific issue.
gitlab_get_pipeline	PIPELINESTOOL	Get information about a specific pipeline in a project.
gitlab_get_pipeline_jobs	PIPELINESTOOL	Get jobs associated with a specific pipeline within a project.
gitlab_get_pipeline_schedule	PIPELINESTOOL	Get information about a specific pipeline schedule in a project.
gitlab_get_pipeline_schedules	PIPELINESTOOL	Get pipeline schedules for a specific project.
gitlab_get_pipelines	PIPELINESTOOL	Get information about pipelines for a specific project.
gitlab_get_pipelines_triggered_from_schedule	PIPELINESTOOL	Get pipelines triggered from a specific pipeline schedule.
gitlab_get_project	PROJECTSTOOL	Get information about a specific project.
gitlab_get_project_contributors	PROJECTSTOOL	Get information about contributors to a project.
gitlab_get_project_deploy_token	PROJECTSTOOL	Get a specific deploy token for a project.
gitlab_get_project_deploy_tokens	PROJECTSTOOL	Get deploy tokens for a specific project.
gitlab_get_project_groups	PROJECTSTOOL	Get groups associated with a specific project.
gitlab_get_project_job	PROJECTSTOOL	Get details of a specific job within a project.
gitlab_get_project_job_log	PROJECTSTOOL	Get the log of a specific job within a project.
gitlab_get_project_jobs	PROJECTSTOOL	Get jobs associated with a specific project.
gitlab_get_project_level_merge_request_rule	PROJECTSTOOL	Get details of a specific project-level merge request approval rule.
gitlab_get_project_level_merge_request_rules	PROJECTSTOOL	Get project-level merge request approval rules.
gitlab_get_project_level_rule	PROJECTSTOOL	Get details of a project-level merge request approval setting.
gitlab_get_project_members	PROJECTSTOOL	Get members of a specific project.
gitlab_get_project_merge_request	PROJECTSTOOL	Get details of a specific merge request in a project.
gitlab_get_project_merge_requests	PROJECTSTOOL	Get merge requests for a specific project.
gitlab_get_project_runners	PROJECTSTOOL	Get information about runners in a project.
gitlab_get_project_statistics	PROJECTSTOOL	Get statistics for a specific project.
gitlab_get_projects	PROJECTSTOOL	Get information about projects.
gitlab_get_protected_branch	REPOSITORIESTOOL	Get information about a specific protected branch in a project.
gitlab_get_protected_branches	REPOSITORIESTOOL	Get information about protected branches in a project.
gitlab_get_protected_environment	ENVIRONMENTSTOOL	Get details of a specific protected environment.
gitlab_get_protected_environments	ENVIRONMENTSTOOL	Get a list of protected environments for a project.
gitlab_get_protected_tag	REPOSITORIESTOOL	Get information about a specific protected tag in a project.
gitlab_get_protected_tags	REPOSITORIESTOOL	Get information about protected tags in a project.
gitlab_get_release_by_tag	REPOSITORIESTOOL	Get information about a release by its tag in a project.
gitlab_get_releases	ENVIRONMENTSTOOL	Get information about releases in a project.
gitlab_get_repository_packages	OTHERTOOL	Get information about repository packages for a specific project.
gitlab_get_runner	PIPELINESTOOL	Get information about a specific runner.
gitlab_get_runner_jobs	PIPELINESTOOL	Get jobs for a specific runner.
gitlab_get_runners	PIPELINESTOOL	Get information about runners.
gitlab_get_snippet	OTHERTOOL	Get a specific snippet.
gitlab_get_snippets	OTHERTOOL	Get list of snippets. Can filter by project_id.
gitlab_get_tag	REPOSITORIESTOOL	Get information about a specific tag in a project.
gitlab_get_tags	REPOSITORIESTOOL	Get information about tags in a project.
gitlab_get_user	USERS_GROUPSTOOL	Get information about a specific user.
gitlab_get_users	USERS_GROUPSTOOL	Get information about users.
gitlab_get_wiki_list	OTHERTOOL	Get a list of wiki pages for a project.
gitlab_get_wiki_page	OTHERTOOL	Get information about a specific wiki page.
gitlab_merge_request_level_approvals	MERGE_REQUESTSTOOL	Get approvals for a specific merge request.
gitlab_pause_runner	PIPELINESTOOL	Pause or unpause a specific runner.
gitlab_post_build_status_to_commit	REPOSITORIESTOOL	Post build status to a commit.
gitlab_protect_branch	REPOSITORIESTOOL	Protect a specific branch in a project.
gitlab_protect_environment	ENVIRONMENTSTOOL	Protect an environment for a project.
gitlab_protect_tag	REPOSITORIESTOOL	Protect a tag in a project.
gitlab_publish_repository_package	OTHERTOOL	Publish a repository package for a specific project.
gitlab_register_new_runner	PIPELINESTOOL	Register a new runner.
gitlab_require_code_owner_approvals_single_branch	REPOSITORIESTOOL	Require code owner approvals for a specific branch in a project.
gitlab_reset_gitlab_runner_token	PIPELINESTOOL	Reset GitLab runner registration token.
gitlab_reset_group_runner_token	PIPELINESTOOL	Reset registration token for a group's runner.
gitlab_reset_project_runner_token	PROJECTSTOOL	Reset registration token for a project's runner.
gitlab_reset_token	OTHERTOOL	Reset authentication token for a runner.
gitlab_retry_project_job	PROJECTSTOOL	Retry a specific job within a project.
gitlab_revert_commit	REPOSITORIESTOOL	Revert a commit.
gitlab_run_pipeline	PIPELINESTOOL	Run a pipeline for a specific project.
gitlab_run_pipeline_schedule	PIPELINESTOOL	Run a pipeline schedule for a specific project.
gitlab_run_project_job	PROJECTSTOOL	Run a specific job within a project.
gitlab_share_project	PROJECTSTOOL	Share a specific project with a group.
gitlab_stop_environment	ENVIRONMENTSTOOL	Stop an environment for a project.
gitlab_stop_stale_environments	ENVIRONMENTSTOOL	Stop stale environments for a project.
gitlab_take_pipeline_schedule_ownership	PIPELINESTOOL	Take ownership of a pipeline schedule for a specific project.
gitlab_unapprove_merge_request	MERGE_REQUESTSTOOL	Unapprove a specific merge request.
gitlab_unarchive_project	PROJECTSTOOL	Unarchive a specific project.
gitlab_unprotect_branch	REPOSITORIESTOOL	Unprotect a specific branch in a project.
gitlab_unprotect_environment	ENVIRONMENTSTOOL	Unprotect an environment for a project.
gitlab_unprotect_tag	REPOSITORIESTOOL	Unprotect a tag in a project.
gitlab_update_environment	ENVIRONMENTSTOOL	Update an existing environment for a project.
gitlab_update_epic	ISSUESTOOL	Update a group epic.
gitlab_update_issue	ISSUESTOOL	Update an issue.
gitlab_update_label	ISSUESTOOL	Update an existing label.
gitlab_update_milestone	ISSUESTOOL	Update a project milestone.
gitlab_update_note	OTHERTOOL	Update a note.
gitlab_update_project_level_rule	PROJECTSTOOL	Update an existing project-level merge request approval rule.
gitlab_update_protected_environment	ENVIRONMENTSTOOL	Update a protected environment for a project.
gitlab_update_release	ENVIRONMENTSTOOL	Update information about a release in a project.
gitlab_update_runner_details	PIPELINESTOOL	Update details for a specific runner.
gitlab_update_snippet	OTHERTOOL	Update a snippet.
gitlab_update_user	USERS_GROUPSTOOL	Update an existing user.
gitlab_update_wiki_page	OTHERTOOL	Update an existing wiki page for a project.
gitlab_upload_wiki_page_attachment	OTHERTOOL	Upload an attachment to a wiki page for a project.
gitlab_verify_runner_authentication	PIPELINESTOOL	Verify runner authentication.

27 action-routed tool(s) (default) · 188 verbose 1:1 tool(s). Each is enabled unless its <DOMAIN>TOOL toggle is set false; MCP_TOOL_MODE selects the surface (condensed default · verbose 1:1 · both). Auto-generated — do not edit.

Detailed tool schemas, parameter shapes, and validation constraints are preserved in docs/mcp.md.

Dynamic Tool Selection & Visibility

This MCP server supports dynamic toolset selection and visibility filtering at runtime. This allows you to restrict the set of exposed tools in order to prevent blowing up the LLM's context window.

You can configure tool filtering via multiple input channels:

• CLI Arguments: Pass --tools or --toolsets (or their disabled counterparts --disabled-tools and --disabled-toolsets) during startup.
• Environment Variables: Define standard environment variables:
  • MCP_ENABLED_TOOLS / MCP_DISABLED_TOOLS
  • MCP_ENABLED_TAGS / MCP_DISABLED_TAGS
• HTTP SSE Request Headers: Pass custom headers during transport initialization:
  • x-mcp-enabled-tools / x-mcp-disabled-tools
  • x-mcp-enabled-tags / x-mcp-disabled-tags
• HTTP SSE Request Query Parameters: Append query parameters directly to your transport connection URL:
  • ?tools=tool1,tool2
  • ?tags=tag1

When query strings or parameters are supplied, an LLM-free Knowledge Graph resolution layer (using DynamicToolOrchestrator) matches query intents against known tool tags, names, or descriptions, with safe fallback and automated 24-hour background cache refreshing.

---

MCP Configuration Examples

Install the slim [mcp] extra. All examples install gitlab-api[mcp] — the MCP-server extra that pulls only the FastMCP / FastAPI tooling (agent-utilities[mcp]). It deliberately excludes the heavy agent runtime (pydantic-ai, the epistemic-graph engine, dspy, llama-index), so uvx / container installs are far smaller. Use the full [agent] extra only when you need the integrated Pydantic AI agent.

stdio Transport (local IDEs — Cursor, Claude Desktop, VS Code)

{
  "mcpServers": {
    "gitlab-mcp": {
      "command": "uvx",
      "args": [
        "--from",
        "gitlab-api[mcp]",
        "gitlab-mcp"
      ],
      "env": {
        "MCP_TOOL_MODE": "condensed",
        "BRANCHESTOOL": "True",
        "COMMITSTOOL": "True",
        "CUSTOM_APITOOL": "True",
        "DEPLOY_TOKENSTOOL": "True",
        "ENVIRONMENTSTOOL": "True",
        "EPICSTOOL": "True",
        "GITLAB_TOKEN": "your_gitlab_token_here",
        "GITLAB_URL": "https://gitlab.example.com",
        "GRAPHQLTOOL": "True",
        "GROUPSTOOL": "True",
        "ISSUESTOOL": "True",
        "JOBSTOOL": "True",
        "LABELSTOOL": "True",
        "MEMBERSTOOL": "True",
        "MERGE_REQUESTSTOOL": "True",
        "MERGE_RULESTOOL": "True",
        "MILESTONESTOOL": "True",
        "MISCTOOL": "True",
        "NOTESTOOL": "True",
        "PACKAGESTOOL": "True",
        "PIPELINESTOOL": "True",
        "PIPELINE_SCHEDULESTOOL": "True",
        "PROJECTSTOOL": "True",
        "PROTECTED_BRANCHESTOOL": "True",
        "RELEASESTOOL": "True",
        "RUNNERSTOOL": "True",
        "SNIPPETSTOOL": "True",
        "TAGSTOOL": "True"
      }
    }
  }
}

Streamable-HTTP Transport (networked / production)

{
  "mcpServers": {
    "gitlab-mcp": {
      "command": "uvx",
      "args": [
        "--from",
        "gitlab-api[mcp]",
        "gitlab-mcp",
        "--transport",
        "streamable-http",
        "--port",
        "8000"
      ],
      "env": {
        "TRANSPORT": "streamable-http",
        "HOST": "0.0.0.0",
        "PORT": "8000",
        "MCP_TOOL_MODE": "condensed",
        "BRANCHESTOOL": "True",
        "COMMITSTOOL": "True",
        "CUSTOM_APITOOL": "True",
        "DEPLOY_TOKENSTOOL": "True",
        "ENVIRONMENTSTOOL": "True",
        "EPICSTOOL": "True",
        "GITLAB_TOKEN": "your_gitlab_token_here",
        "GITLAB_URL": "https://gitlab.example.com",
        "GRAPHQLTOOL": "True",
        "GROUPSTOOL": "True",
        "ISSUESTOOL": "True",
        "JOBSTOOL": "True",
        "LABELSTOOL": "True",
        "MEMBERSTOOL": "True",
        "MERGE_REQUESTSTOOL": "True",
        "MERGE_RULESTOOL": "True",
        "MILESTONESTOOL": "True",
        "MISCTOOL": "True",
        "NOTESTOOL": "True",
        "PACKAGESTOOL": "True",
        "PIPELINESTOOL": "True",
        "PIPELINE_SCHEDULESTOOL": "True",
        "PROJECTSTOOL": "True",
        "PROTECTED_BRANCHESTOOL": "True",
        "RELEASESTOOL": "True",
        "RUNNERSTOOL": "True",
        "SNIPPETSTOOL": "True",
        "TAGSTOOL": "True"
      }
    }
  }
}

Alternatively, connect to a pre-deployed Streamable-HTTP instance by url:

{
  "mcpServers": {
    "gitlab-mcp": {
      "url": "http://localhost:8000/gitlab-mcp/mcp"
    }
  }
}

Deploying the Streamable-HTTP server via Docker:

docker run -d \
  --name gitlab-mcp-mcp \
  -p 8000:8000 \
  -e TRANSPORT=streamable-http \
  -e HOST=0.0.0.0 \
  -e PORT=8000 \
  -e MCP_TOOL_MODE=condensed \
  -e BRANCHESTOOL=True \
  -e COMMITSTOOL=True \
  -e CUSTOM_APITOOL=True \
  -e DEPLOY_TOKENSTOOL=True \
  -e ENVIRONMENTSTOOL=True \
  -e EPICSTOOL=True \
  -e GITLAB_TOKEN=your_gitlab_token_here \
  -e GITLAB_URL=https://gitlab.example.com \
  -e GRAPHQLTOOL=True \
  -e GROUPSTOOL=True \
  -e ISSUESTOOL=True \
  -e JOBSTOOL=True \
  -e LABELSTOOL=True \
  -e MEMBERSTOOL=True \
  -e MERGE_REQUESTSTOOL=True \
  -e MERGE_RULESTOOL=True \
  -e MILESTONESTOOL=True \
  -e MISCTOOL=True \
  -e NOTESTOOL=True \
  -e PACKAGESTOOL=True \
  -e PIPELINESTOOL=True \
  -e PIPELINE_SCHEDULESTOOL=True \
  -e PROJECTSTOOL=True \
  -e PROTECTED_BRANCHESTOOL=True \
  -e RELEASESTOOL=True \
  -e RUNNERSTOOL=True \
  -e SNIPPETSTOOL=True \
  -e TAGSTOOL=True \
  knucklessg1/gitlab-api:mcp

Auto-generated from the code-read env surface (MCP_TOOL_MODE + package vars) — do not edit.

Additional Deployment Options

gitlab-api can also run as a local container (Docker / Podman / uv) or be consumed from a remote deployment. The Deployment guide has full, copy-paste mcp_config.json for all four transports — stdio, streamable-http, local container / uv, and remote URL:

• Local container / uv — launch the server from mcp_config.json via uvx, docker run, or podman run, or point at a local streamable-http container by url.
• Remote URL — connect to a server deployed behind Caddy at http://gitlab-mcp.arpa/mcp using the "url" key.

---

Environment Variables

Package environment variables

Variable	Example	Description
HOST	0.0.0.0
PORT	8000
TRANSPORT	stdio	options: stdio, streamable-http, sse
ENABLE_OTEL	True
OTEL_EXPORTER_OTLP_ENDPOINT	http://localhost:8080/api/public/otel
OTEL_EXPORTER_OTLP_PUBLIC_KEY	pk-...
OTEL_EXPORTER_OTLP_SECRET_KEY	sk-...
OTEL_EXPORTER_OTLP_PROTOCOL	http/protobuf
EUNOMIA_TYPE	none	options: none, embedded, remote
EUNOMIA_POLICY_FILE	mcp_policies.json
EUNOMIA_REMOTE_URL	http://eunomia-server:8000
GITLAB_URL	https://gitlab.example.com
GITLAB_TOKEN	your_gitlab_token_here
GITLAB_SSL_VERIFY	True	verify TLS certs; set False for self-signed homelab instances
MISCTOOL	True
BRANCHESTOOL	True
PROTECTED_BRANCHESTOOL	True
COMMITSTOOL	True
DEPLOY_TOKENSTOOL	True
ENVIRONMENTSTOOL	True
EPICSTOOL	True
GROUPSTOOL	True
ISSUESTOOL	True
JOBSTOOL	True
LABELSTOOL	True
MEMBERSTOOL	True
MERGE_REQUESTSTOOL	True
MERGE_RULESTOOL	True
MILESTONESTOOL	True
NOTESTOOL	True
PACKAGESTOOL	True
PIPELINESTOOL	True
PIPELINE_SCHEDULESTOOL	True
PROJECTSTOOL	True
RELEASESTOOL	True
RUNNERSTOOL	True
SNIPPETSTOOL	True
TAGSTOOL	True
CUSTOM_APITOOL	True
GRAPHQLTOOL	True

Inherited agent-utilities variables (apply to every connector)

Variable	Example	Description
MCP_TOOL_MODE	condensed	Tool surface: condensed
MCP_ENABLED_TOOLS	—	Comma-separated tool allow-list
MCP_DISABLED_TOOLS	—	Comma-separated tool deny-list
MCP_ENABLED_TAGS	—	Comma-separated tag allow-list
MCP_DISABLED_TAGS	—	Comma-separated tag deny-list
MCP_CLIENT_AUTH	—	Outbound MCP auth (oidc-client-credentials for fleet calls)
OIDC_CLIENT_ID	—	OIDC client id (service-account auth)
OIDC_CLIENT_SECRET	—	OIDC client secret (service-account auth)
DEBUG	False	Verbose logging
PYTHONUNBUFFERED	1	Unbuffered stdout (recommended in containers)
MCP_URL	http://localhost:8000/mcp	URL of the MCP server the agent connects to
PROVIDER	openai	LLM provider for the agent
MODEL_ID	gpt-4o	Model id for the agent
ENABLE_WEB_UI	True	Serve the AG-UI web interface

40 package + 14 inherited variable(s). Auto-generated from .env.example + the shared agent-utilities set — do not edit.

Every variable the server reads.

Connection & Credentials

The connector is single-host by default and multi-tenant when gitlab_instances is configured (see Multi-Tenancy). When no instances are configured, it falls back to the single-host GITLAB_* values below.

Variable	Description	Default
GITLAB_URL	Base GitLab instance URL	https://gitlab.example.com
GITLAB_TOKEN	GitLab personal/project access token (glpat-…)	—
GITLAB_SSL_VERIFY	TLS certificate verification	True

Multiple instances are declared once under gitlab_instances in the shared agent-utilities XDG config (~/.config/agent-utilities/config.json) — each entry has name, url, token, and verify_ssl. Target a tenant by name from the client factory; an unset instance resolves to the first configured one (else GITLAB_URL / GITLAB_TOKEN).

MCP server / transport

Variable	Description	Default
TRANSPORT	stdio, streamable-http, or sse	stdio
HOST	Bind host (HTTP transports)	0.0.0.0
PORT	Bind port (HTTP transports)	8000
MCP_TOOL_MODE	Tool surface: condensed, verbose, or both	condensed
MCP_ENABLED_TOOLS / MCP_DISABLED_TOOLS	Comma-separated tool allow/deny list	—
MCP_ENABLED_TAGS / MCP_DISABLED_TAGS	Comma-separated tag allow/deny list	—
DEBUG	Verbose logging	False
PYTHONUNBUFFERED	Unbuffered stdout (recommended in containers)	1

Tool toggles

Each action-routed tool can be disabled individually via its toggle env var (set to false). The full list is in the Available MCP Tools table above (e.g. PROJECTSTOOL, MERGE_REQUESTSTOOL, PIPELINESTOOL, GRAPHQLTOOL, CUSTOM_APITOOL).

Telemetry & governance

Variable	Description	Default
ENABLE_OTEL	Enable OpenTelemetry export	True
OTEL_EXPORTER_OTLP_ENDPOINT	OTLP collector endpoint	—
OTEL_EXPORTER_OTLP_PUBLIC_KEY / OTEL_EXPORTER_OTLP_SECRET_KEY	OTLP auth keys	—
OTEL_EXPORTER_OTLP_PROTOCOL	OTLP protocol (e.g. http/protobuf)	—
EUNOMIA_TYPE	Authorization mode: none, embedded, remote	none
EUNOMIA_POLICY_FILE	Embedded policy file	mcp_policies.json
EUNOMIA_REMOTE_URL	Remote Eunomia server URL	—

Agent CLI (full [agent] runtime only)

Variable	Description	Default
MCP_URL	URL of the MCP server the agent connects to	http://localhost:8000/mcp
PROVIDER	LLM provider (e.g. openai)	openai
MODEL_ID	Model id (e.g. gpt-4o)	gpt-4o
ENABLE_WEB_UI	Serve the AG-UI web interface	True

See .env.example for a copy-paste starting point.

Agent

This repository features a fully integrated Pydantic AI Graph Agent. It communicates over the Agent Control Protocol (ACP) and interacts seamlessly with the Agent Web UI (AG-UI) and Terminal interface.

Running the Agent CLI

To start the interactive command-line agent:

# Set credentials
export GITLAB_URL="your_value"
export GITLAB_TOKEN="your_value"

# Run the agent server
gitlab-agent --provider openai --model-id gpt-4o

Docker Compose Orchestration

The following docker/agent.compose.yml configures the Agent, Web UI, and Terminal Interface together:

version: '3.8'

services:
  gitlab-api-mcp:
    image: knucklessg1/gitlab-api:mcp
    container_name: gitlab-api-mcp
    hostname: gitlab-api-mcp
    restart: always
    env_file:
      - ../.env
    environment:
      - PYTHONUNBUFFERED=1
      - HOST=0.0.0.0
      - PORT=8000
      - TRANSPORT=streamable-http
    ports:
      - "8000:8000"
    healthcheck:
      test: ["CMD", "python3", "-c", "import urllib.request; urllib.request.urlopen('http://localhost:8000/health')"]
      interval: 30s
      timeout: 10s
      retries: 3
      start_period: 10s
    logging:
      driver: json-file
      options:
        max-size: "10m"
        max-file: "3"

  gitlab-api-agent:
    image: knucklessg1/gitlab-api:latest
    container_name: gitlab-api-agent
    hostname: gitlab-api-agent
    restart: always
    depends_on:
      - gitlab-api-mcp
    env_file:
      - ../.env
    command: [ "gitlab-agent" ]
    environment:
      - PYTHONUNBUFFERED=1
      - HOST=0.0.0.0
      - PORT=9017
      - MCP_URL=http://gitlab-api-mcp:8000/mcp
      - PROVIDER=${PROVIDER:-openai}
      - MODEL_ID=${MODEL_ID:-gpt-4o}
      - ENABLE_WEB_UI=True
      - ENABLE_OTEL=True
    ports:
      - "9017:9017"
    healthcheck:
      test: ["CMD", "python3", "-c", "import urllib.request; urllib.request.urlopen('http://localhost:9017/health')"]
      interval: 30s
      timeout: 10s
      retries: 3
      start_period: 10s
    logging:
      driver: json-file
      options:
        max-size: "10m"
        max-file: "3"

Detailed graph node architecture explanations, custom skill configurations, and agentic trace guides are available in docs/agent.md.

---

Multi-Tenancy (multiple GitLab instances)

The client is natively multi-tenant. The set of instances is declared once in the shared agent-utilities XDG config (~/.config/agent-utilities/config.json) under gitlab_instances — the same list the Knowledge-Graph GitLab indexer reads, so one config drives both code/metadata indexing and every API/MCP call:

{
  "gitlab_instances": [
    {"name": "internal", "url": "https://gitlab.arpa", "token": "glpat-xxxx", "verify_ssl": false},
    {"name": "public",   "url": "https://gitlab.com",  "token": "glpat-yyyy", "verify_ssl": true}
  ]
}

Target a tenant by name from the client factory; a bare URL still works, and an unset instance resolves to the first configured one (else GITLAB_URL/GITLAB_TOKEN):

from gitlab_api.auth import get_client
from gitlab_api.instances import list_configured_instances

internal = get_client(instance="internal")   # resolves url+token+verify from config
public   = get_client(instance="public")
default  = get_client()                        # first configured / GITLAB_URL fallback
names    = [i.name for i in list_configured_instances()]

The MCP server exposes a gitlab_instances tool (action=list|get) to discover the configured tenants (tokens are never returned). When no instances are configured, the connector falls back to the single-host GITLAB_URL/GITLAB_TOKEN it has always used.

Security & Governance

Built directly upon the enterprise-ready agent-utilities core, standard security parameters are fully supported:

Access Control & Policy Enforcement

• Eunomia Policies: Fine-grained, policy-driven tool authorization. Supports none, local embedded (mcp_policies.json), or centralized remote modes.
• OIDC Token Delegation: Compliant with RFC 8693 token exchange for flowing authenticating user credentials from Web UI / ACP → Agent → MCP.
• Scoped Credentials: Execution context runs restricted to the specific caller identity.

Runtime Security Grid

Feature	Functionality	Enablement
Tool Guard	Sensitivity inspection with human-in-the-loop validation	Enabled by default
Prompt Injection Defense	Input scanning, repetition monitoring, and recursive loop blocks	Enabled by default
Context Safety Guard	Stuck-loop detectors and contextual overflow preemptive alerts	Enabled by default

---

Installation

Pick the extra that matches what you want to run:

Extra	Installs	Use when
gitlab-api[mcp]	Slim MCP server only (agent-utilities[mcp] — FastMCP/FastAPI)	You only run the MCP server (smallest install / image)
gitlab-api[agent]	Full agent runtime (agent-utilities[agent,logfire] — Pydantic AI + the epistemic-graph engine)	You run the integrated agent
gitlab-api[all]	Everything (mcp + agent + gql + logfire)	Development / both surfaces

# MCP server only (recommended for tool hosting — slim deps)
uv pip install "gitlab-api[mcp]"

# Full agent runtime (Pydantic AI + epistemic-graph engine)
uv pip install "gitlab-api[agent]"

# Everything (development)
uv pip install "gitlab-api[all]"      # or: python -m pip install "gitlab-api[all]"

Container images (:mcp vs :agent)

One multi-stage docker/Dockerfile builds two right-sized images, selected by --target:

Image tag	Build target	Contents	Entrypoint
knucklessg1/gitlab-api:mcp	--target mcp	gitlab-api[mcp] — slim, no engine/pydantic-ai/dspy/llama-index/tree-sitter	gitlab-mcp
knucklessg1/gitlab-api:latest	--target agent (default)	gitlab-api[agent] — full agent runtime + epistemic-graph engine	gitlab-agent

docker build --target mcp   -t knucklessg1/gitlab-api:mcp    docker/   # slim MCP server
docker build --target agent -t knucklessg1/gitlab-api:latest docker/   # full agent

docker/mcp.compose.yml runs the slim :mcp server; docker/agent.compose.yml runs the agent (:latest) with a co-located :mcp sidecar.

Knowledge-graph database (epistemic-graph)

The full agent ([agent] / :latest) embeds the epistemic-graph engine (pulled in transitively via agent-utilities[agent]). For production — or to share one knowledge graph across multiple agents — run epistemic-graph as its own database container and point the agent at it instead of embedding it. Deployment recipes (single-node + Raft HA), connection config, and the full database architecture (with diagrams) are documented in the epistemic-graph deployment guide. The slim [mcp] server does not require the database.

---

Documentation

The complete documentation is published as the official documentation site and is the recommended reference for installation, deployment, and day-to-day operation.

Page	Contents
Installation	pip, source, extras, prebuilt Docker image
Deployment	run the MCP and agent servers, Compose, Caddy + Technitium, env config
Usage	the MCP tools, the Api client, the CLI
Backing Platform	deploy GitLab with Docker
Overview	the action-routed tool surface and architecture
Concepts	concept registry (CONCEPT:GL-*)

---

Repository Owners

---

Contribute

Contributions are welcome! Please ensure code quality by executing local checks before submitting pull requests:

• Format code using ruff format .
• Lint code using ruff check .
• Validate type-safety with mypy .
• Execute test suites using pytest

Deploy with agent-os-genesis

This package can be provisioned for you — skill-guided — by the agent-os-genesis universal skill (its single-package deploy mode): it picks your install method, seeds secrets to OpenBao/Vault (or .env), trusts your enterprise CA, registers the MCP server, and verifies it — the same machinery that stands up the whole Agent OS, narrowed to just this package. Ask your agent to "deploy gitlab-api with agent-os-genesis".

Install mode	Command
Bare-metal, prod (PyPI)	uvx gitlab-mcp · or uv tool install gitlab-api
Bare-metal, dev (editable)	uv pip install -e ".[all]" · or pip install -e ".[all]"
Container, prod	deploy knucklessg1/gitlab-api:latest via docker-compose / swarm / podman / podman-compose / kubernetes
Container, dev (editable)	deploy docker/compose.dev.yml (source-mounted at /src; edits live on restart)

Secrets are read-existing + seeded via vault_sync — you are only prompted for what's missing.