Skip to content
Back to search

mcp-gitlab14

GraphQL-first MCP server for GitLab 14+ with REST API support. Manage issues and explore merge requests, repositories, and CI/CD over Streamable HTTP.

Safety scan

A static text scan, not a guarantee. Select the badge to see what was scanned and every finding.

Checked today
Badge for your README
findsafeskills safety rating

Markdown

[![findsafeskills safety rating](/api/listings/alexbal1313--mcp-gitlab14/badge.svg)](/listings/alexbal1313--mcp-gitlab14)

HTML

<a href="/listings/alexbal1313--mcp-gitlab14"><img src="/api/listings/alexbal1313--mcp-gitlab14/badge.svg" alt="findsafeskills safety rating" /></a>

Install

i

Install instructions from the README

As written by the repo's author. findsafeskills has not verified these steps.

Clone or download this repository and open its root directory. Set your GitLab URL, then start the server:

export GITLAB_BASE_URI=https://gitlab.example.com
TOKEN_GITLAB=<token> ./mvnw quarkus:dev

Replace the URL and `<token>` with your instance URL and token. The default URL is a placeholder, not a hosted service.

What was scanned

The files the safety scan read, as written by the repository's author and shown as plain text. Lines with a finding are marked.

README.md · README · 501 lines
  1. # MCP GitLab 14.x+
  2. ## Contents
  3. - [What it is](#what-it-is)
  4. - [Why GraphQL first?](#why-graphql-first)
  5. - [Requirements](#requirements)
  6. - [Quick start](#quick-start)
  7. - [Configuration and HTTPS](#configuration)
  8. - [AI agent configuration](#ai-agent-configuration)
  9. - [Tools](#tools)
  10. - [Tool arguments and response contracts](#tool-arguments-and-response-contracts)
  11. - [GitLab compatibility](#gitlab-compatibility)
  12. - [Build & test](#build--test)
  13. - [Docker](#docker)
  14. - [License](#license)
  15. - [Contributing and security](#contributing-and-security)
  16. ## What it is
  17. An MCP server for GitLab, built with Quarkus. It exposes **33 tools
  18. (28 read + 5 write)** over **Streamable HTTP** at `/mcp`.
  19. GraphQL is used where supported by the verified GitLab 14 schema;
  20. REST v4 covers the remaining operations.
  21. ## Why GraphQL first?
  22. **GraphQL is the preferred GitLab API in this server.** Queries select only
  23. the fields the tool needs and fetch related data, such as issue authors,
  24. assignees, labels, and milestones, together. This reduces over-fetching and
  25. the need for separate requests for related entities.
  26. **REST v4 is used where the required functionality is unavailable in the
  27. verified GitLab GraphQL schema.** Examples include cross-project issue and
  28. merge request searches, code search, commit and tag operations, and issue
  29. writes. Job logs combine GraphQL job lookup with REST trace retrieval.
  30. This is an explicit per-operation API choice, not an automatic fallback:
  31. a failed GraphQL request is reported as an error, not silently retried
  32. through REST. The tool tables below show the API used by each operation.
  33. ## Requirements
  34. - JDK 25.
  35. - Maven: use `./mvnw` (Maven 3.9.16 is downloaded on the first run).
  36. - A reachable GitLab instance.
  37. - A GitLab token with API read access to the projects you need (`read_api`
  38. for read-only use). Write tools require the `api` scope and permission to
  39. modify those projects. Create the token in your GitLab access token settings;
  40. scopes do not grant access to projects the token's identity cannot access.
  41. - Port `8004` available.
  42. ## Quick start
  43. Clone or download this repository and open its root directory.
  44. Set your GitLab URL, then start the server:
  45. ```bash
  46. export GITLAB_BASE_URI=https://gitlab.example.com
  47. TOKEN_GITLAB=<token> ./mvnw quarkus:dev
  48. ```
  49. Replace the URL and `<token>` with your instance URL and token.
  50. The default URL is a placeholder, not a hosted service.
  51. ## Configuration
  52. | Environment variable | Purpose | Default |
  53. |---|---|---|
  54. | `TOKEN_GITLAB` | Shared GitLab service token | Required |
  55. | `GITLAB_BASE_URI` | GitLab instance base URL | `https://gitlab.example.com` |
  56. | `QUARKUS_HTTP_PORT` | HTTP port | `8004` |
  57. | `QUARKUS_HTTP_HOST` | HTTP bind address | `0.0.0.0` |
  58. The token is configured on the server, never passed as a tool argument.
  59. All callers use that token's permissions. The server does not configure
  60. MCP client authentication and includes write tools by default. Do not expose
  61. it to untrusted networks; restrict access or use an authenticating reverse proxy.
  62. For local-only access, set `QUARKUS_HTTP_HOST=127.0.0.1`.
  63. ### HTTPS and private certificate authorities
  64. Both GitLab clients verify TLS certificates. Publicly trusted HTTPS endpoints
  65. need no extra settings. For a corporate or self-signed certificate chain,
  66. obtain the trusted CA certificate from your administrator and verify its
  67. fingerprint through a trusted channel. Do not disable certificate or hostname
  68. verification.
  69. Create a local trust store containing the JDK's public roots and your CA
  70. (first-time setup; do not overwrite an existing custom store):
  71. ```bash
  72. mkdir -p .certs
  73. keytool -importkeystore \
  74. -srckeystore "$JAVA_HOME/lib/security/cacerts" -srcstorepass changeit \
  75. -destkeystore .certs/gitlab-truststore.p12 -deststoretype PKCS12 \
  76. -deststorepass changeit -noprompt
  77. keytool -importcert -alias gitlab-company-ca -file /path/to/company-ca.pem \
  78. -keystore .certs/gitlab-truststore.p12 -storetype PKCS12 \
  79. -storepass changeit -noprompt
  80. ```
  81. For a packaged JVM application:
  82. ```bash
  83. export JAVA_TOOL_OPTIONS="-Djavax.net.ssl.trustStore=$PWD/.certs/gitlab-truststore.p12 -Djavax.net.ssl.trustStorePassword=changeit -Djavax.net.ssl.trustStoreType=PKCS12"
  84. java -jar target/quarkus-app/quarkus-run.jar
  85. ```
  86. Set `TOKEN_GITLAB` and `GITLAB_BASE_URI` as usual. Both clients honor the JVM
  87. trust store; the test suite checks this without disabling TLS verification.
  88. The password above protects a store of public CA certificates, not private keys.
  89. For Docker, create an optional `compose.ca.yaml` override:
  90. ```yaml
  91. services:
  92. mcp-gitlab:
  93. volumes:
  94. - ./.certs/gitlab-truststore.p12:/deployments/tls/gitlab-truststore.p12:ro
  95. environment:
  96. JAVA_TOOL_OPTIONS: >-
  97. -Djavax.net.ssl.trustStore=/deployments/tls/gitlab-truststore.p12
  98. -Djavax.net.ssl.trustStorePassword=changeit
  99. -Djavax.net.ssl.trustStoreType=PKCS12
  100. ```
  101. Then use both Compose files, including for subsequent updates and shutdown:
  102. ```bash
  103. docker compose -f compose.yaml -f compose.ca.yaml up -d
  104. docker compose -f compose.yaml -f compose.ca.yaml down
  105. ```
  106. The container runs as UID 185; make sure it can read the mounted certificate
  107. store. `.certs/` is excluded from Git and the Docker build context.
  108. ## AI agent configuration
  109. Start the server before connecting your agent. The two URLs serve different purposes:
  110. - `GITLAB_BASE_URI`: the GitLab instance the server connects to.
  111. - `http://localhost:8004/mcp`: the MCP endpoint your agent connects to.
  112. The GitLab token belongs on the server, not in agent configuration or prompts.
  113. One server process connects to one GitLab instance using one shared token.
  114. Agent-side tool approval is recommended, especially for the five write tools.
  115. ### Claude Code
  116. Register the server for the current project:
  117. ```bash
  118. claude mcp add --transport http gitlab --scope project http://localhost:8004/mcp
  119. ```
  120. Alternatively, add this to `.mcp.json` in your agent project's root:
  121. ```json
  122. {
  123. "mcpServers": {
  124. "gitlab": {
  125. "type": "http",
  126. "url": "http://localhost:8004/mcp"
  127. }
  128. }
  129. }
  130. ```
  131. Use `claude mcp list` or `/mcp` inside Claude Code to check the connection.
  132. ### Cursor
  133. Add to `.cursor/mcp.json` in your agent project, or `~/.cursor/mcp.json` globally:
  134. ```json
  135. {
  136. "mcpServers": {
  137. "gitlab": {
  138. "url": "http://localhost:8004/mcp"
  139. }
  140. }
  141. }
  142. ```
  143. ### VS Code / GitHub Copilot
  144. For an editor-managed workspace configuration, add `.vscode/mcp.json`:
  145. ```json
  146. {
  147. "servers": {
  148. "gitlab": {
  149. "type": "http",
  150. "url": "http://localhost:8004/mcp"
  151. }
  152. }
  153. }
  154. ```
  155. You can also use **MCP: Add Server** in the Command Palette and select HTTP.
  156. These examples use **Streamable HTTP**, not stdio or the legacy SSE endpoint.
  157. They follow the clients' configuration formats; interactive client UI behavior
  158. has not been tested here. See the official
  159. [Claude Code](https://code.claude.com/docs/en/mcp),
  160. [Cursor](https://cursor.com/docs/context/mcp), and
  161. [VS Code](https://code.visualstudio.com/docs/agents/reference/mcp-configuration)
  162. documentation for version-specific details.
  163. For an agent running in a container or on another machine, `localhost`
  164. refers to that environment, not necessarily the MCP server's host.
  165. Use a reachable, authenticated endpoint; the supplied Compose configuration
  166. intentionally publishes the service on the host loopback interface only.
  167. ### Example agent tasks
  168. - "List open issues in team/project assigned to alice."
  169. - "Review merge request !3 in team/project, including its diff and discussions."
  170. - "Show the last 100 log lines for job unit in pipeline IID 12 of team/project."
  171. - "Create an issue in team/project after showing me the proposed title and body."
  172. Use tools only against projects the shared server token is authorized to access.
  173. ## Tools
  174. ### Read tools (28)
  175. | Group | Tool | Purpose | GitLab API | Key arguments |
  176. |---|---|---|---|---|
  177. | Projects | `gitlab_list_projects` | List accessible projects | GraphQL | `query`, `items`, `afterCursor` |
  178. | Projects | `gitlab_get_project` | Get project details | GraphQL | `projectFullPath` |
  179. | Projects | `gitlab_list_active_projects` | List projects active during a period | REST | `updatedAfter` and/or `updatedBefore` |
  180. | Issues | `gitlab_list_project_issues` | List and filter project issues | GraphQL | `projectFullPath`, `state`, `query` |
  181. | Issues | `gitlab_get_issue` | Get issue details | GraphQL | `projectFullPath`, `iid` |
  182. | Issues | `gitlab_search_issues` | Search issues across accessible projects | REST | `query`, `state`, `labels`, date filters |
  183. | Issues | `gitlab_list_issue_discussions` | List issue discussions and notes | GraphQL | `projectFullPath`, `iid` |
  184. | Merge requests | `gitlab_list_project_merge_requests` | List and filter project merge requests | GraphQL | `projectFullPath`, `state` |
  185. | Merge requests | `gitlab_get_merge_request` | Get merge request details | GraphQL | `projectFullPath`, `iid` |
  186. | Merge requests | `gitlab_get_merge_request_diff` | Get the current merge request diff | REST | `projectFullPath`, `iid`, `items`, `afterCursor` |
  187. | Merge requests | `gitlab_search_merge_requests` | Search across accessible projects | REST | `query`, `state`, `labels`, date filters |
  188. | Merge requests | `gitlab_list_merge_request_discussions` | List discussions and notes | GraphQL | `projectFullPath`, `iid` |
  189. | Code search | `gitlab_search_code` | Search code snippets in one project | REST | `projectFullPath`, `query`, `ref`, `path`, `extension` |
  190. | File content | `gitlab_get_file_content` | Read a bounded text file line range at a revision | GraphQL | `projectFullPath`, `path`, `ref`, `startLine`, `endLine` |
  191. | Commits | `gitlab_list_project_commits` | List project commits | REST | `projectFullPath`, `refName`, `since`, `until` |
  192. | Commits | `gitlab_get_commit` | Get a commit by SHA, branch, or tag | REST | `projectFullPath`, `sha` |
  193. | Commits | `gitlab_get_commit_diff` | Get a commit diff | REST | `projectFullPath`, `sha`, `items`, `afterCursor` |
  194. | Tags | `gitlab_list_tags` | List project tags | REST | `projectFullPath`, `items`, `afterCursor` |
  195. | Tags | `gitlab_get_tag` | Get a tag by name | REST | `projectFullPath`, `tagName` |
  196. | Repository tree | `gitlab_list_dir` | List files and folders without recursion | REST | `projectFullPath`, `path`, `ref` |
  197. | Users | `gitlab_search_users` | Search users by name or username using Latin letters | REST | `userName`, `items`, `afterCursor` |
  198. | Pipelines | `gitlab_list_project_pipelines` | List and filter project pipelines | GraphQL | `projectFullPath`, `status`, `ref`, date filters |
  199. | Pipelines | `gitlab_get_pipeline` | Get pipeline details | GraphQL | `projectFullPath`, `pipelineIid` |
  200. | Jobs | `gitlab_list_pipeline_jobs` | List pipeline jobs | GraphQL | `projectFullPath`, `pipelineIid`, `status` |
  201. | Jobs | `gitlab_get_job` | Get a pipeline job by name | GraphQL | `projectFullPath`, `pipelineIid`, `jobName` |
  202. | Jobs | `gitlab_get_job_log` | Get the tail of a job log | GraphQL + REST | `projectFullPath`, `pipelineIid`, `jobName`, `lines` |
  203. | Labels | `gitlab_list_project_labels` | List project labels | REST | `projectFullPath`, `items`, `afterCursor` |
  204. | Milestones | `gitlab_list_project_milestones` | List project milestones | REST | `projectFullPath`, `items`, `afterCursor` |
  205. ### Write tools (5)
  206. | Group | Tool | Purpose | GitLab API | Key arguments |
  207. |---|---|---|---|---|
  208. | Issues | `gitlab_create_issue` | Create an issue with optional labels and milestone | REST | `projectFullPath`, `title`, `description`, `labels`, `milestone` |
  209. | Issues | `gitlab_create_issue_note` | Add an issue comment | REST | `projectFullPath`, `iid`, `body` |
  210. | Labels | `gitlab_modify_issue_labels` | Add or remove issue labels | REST | `projectFullPath`, `iid`, `action`, `labels` |
  211. | Assignees | `gitlab_assign_issue` | Replace all assignees; an empty array removes all | REST | `projectFullPath`, `iid`, `assignees` |
  212. | Milestones | `gitlab_assign_issue_milestone` | Assign or remove an issue milestone | REST | `projectFullPath`, `iid`, `milestone` |
  213. ## Tool arguments and response contracts
  214. The tables show key arguments, not the complete JSON schemas. MCP `tools/list`
  215. returns the authoritative input schema, including required fields, types, enums,
  216. and optional filters, for each tool.
  217. - `projectFullPath` is a full namespace path, such as `team/subgroup/project`.
  218. - Issue and merge request `iid` values are project-scoped numbers, not global IDs.
  219. `pipelineIid` is also project-scoped; jobs are selected by `jobName` within it.
  220. - Date filters use ISO 8601 timestamps with a timezone, such as
  221. `2026-01-02T03:04:05Z`.
  222. - `items` is 1–20, default 20. Paginated tools return `items` and
  223. `pageInfo: {endCursor, hasNextPage}`. Pass the returned `endCursor` unchanged
  224. as `afterCursor` until `hasNextPage` is false.
  225. - GraphQL cursors are opaque strings. REST-backed list and diff tools use
  226. positive page numbers encoded as strings. Cursors are not interchangeable.
  227. - Code search returns up to 20 snippets and a `truncated` flag, not a cursor.
  228. - File content uses 1-based inclusive line ranges, capped at 500 lines per call.
  229. Truncated results include `nextStartLine`; binary/unavailable text returns
  230. `contentAvailable: false`.
  231. - Job log tails default to 200 lines and accept 1–500; results include
  232. `text`, `totalLines`, and `truncated`.
  233. - `gitlab_assign_issue` replaces all assignees; an empty array removes all.
  234. An empty/omitted milestone removes the assignment in `gitlab_assign_issue_milestone`.
  235. - Write tools are enabled by default. There are no tools for deleting issues,
  236. creating/merging merge requests, or starting/retrying pipelines in this version.
  237. ### Example tool calls
  238. After MCP initialization, a `tools/call` JSON-RPC request looks like this:
  239. ```json
  240. {
  241. "jsonrpc": "2.0",
  242. "id": 2,
  243. "method": "tools/call",
  244. "params": {
  245. "name": "gitlab_list_project_issues",
  246. "arguments": {
  247. "projectFullPath": "team/project",
  248. "state": "opened",
  249. "assigneeUsername": "alice",
  250. "items": 10
  251. }
  252. }
  253. }
  254. ```
  255. An issue creation call uses these parameters (ask for approval before writing):
  256. ```json
  257. {
  258. "name": "gitlab_create_issue",
  259. "arguments": {
  260. "projectFullPath": "team/project",
  261. "title": "Investigate failing build",
  262. "description": "The unit job fails on the main branch.",
  263. "labels": ["bug"]
  264. }
  265. }
  266. ```
  267. Successful calls return `result.isError: false`, a machine-readable
  268. `result.structuredContent` object, and the same JSON serialized in a text
  269. content block for older clients. A paginated payload has this shape:
  270. ```json
  271. {
  272. "items": [],
  273. "pageInfo": {
  274. "endCursor": null,
  275. "hasNextPage": false
  276. }
  277. }
  278. ```
  279. Application errors return `result.isError: true` and a structured payload such as:
  280. ```json
  281. {
  282. "code": "NOT_FOUND",
  283. "message": "Object not found"
  284. }
  285. ```
  286. Expected error codes are `VALIDATION_ERROR`, `NOT_FOUND`, `ACCESS_DENIED`, and
  287. `GITLAB_ERROR`. Unexpected runtime failures currently use `exception`.
  288. MCP/framework validation errors may instead contain text-only tool errors;
  289. unknown tool names return a JSON-RPC error. Do not assume every failure has
  290. `structuredContent`, or that HTTP 200 means a successful tool execution.
  291. ## GitLab compatibility
  292. Tested on **GitLab 14**, with GraphQL operations verified against its schema.
  293. Compatibility with other GitLab versions has not been established.
  294. The automated suite uses synthetic HTTP fixtures and is not proof of live
  295. compatibility with every GitLab installation.
  296. Current limits: one GitLab instance and shared token per process; no per-agent
  297. GitLab identities. Milestone assignment currently resolves titles from the
  298. first 100 project milestones. GitLab 14 merge request diffs are fetched as a
  299. whole and paginated locally; upstream diff limits can still truncate results.
  300. ## Build & test
  301. ```bash
  302. ./mvnw package
  303. ```
  304. This compiles the application, runs unit and HTTP integration tests, and builds
  305. the JVM package. Tests cover all 33 tools through the real MCP endpoint;
  306. only the external GitLab API is replaced. No real GitLab token is required.
  307. Both GitLab clients are also tested against trusted and untrusted HTTPS.
  308. For the full Maven verification lifecycle:
  309. ```bash
  310. ./mvnw clean verify
  311. ```
  312. See [CONTRIBUTING.md](CONTRIBUTING.md) for test and contribution guidance.
  313. To run it:
  314. ```bash
  315. GITLAB_BASE_URI=https://gitlab.example.com TOKEN_GITLAB=<token> \
  316. java -jar target/quarkus-app/quarkus-run.jar
  317. ```
  318. ## Docker
  319. ### Requirements
  320. Install JDK 25 and Docker with the Compose plugin. Use the Maven Wrapper
  321. included in the repository. Run the following commands from the project root.
  322. Compose builds the image using `src/main/docker/Dockerfile.jvm`; it does not
  323. compile Java sources, so the JVM package must be built first.
  324. ### First deployment
  325. 1. Create a local configuration file. If `.env` already exists, edit it
  326. instead of overwriting it:
  327. ```bash
  328. cp .env.example .env
  329. chmod 600 .env
  330. ```
  331. 2. Edit `.env`, replacing both placeholders with your GitLab token and URL:
  332. ```dotenv
  333. TOKEN_GITLAB=replace-with-your-gitlab-token
  334. GITLAB_BASE_URI=https://gitlab.example.com
  335. ```
  336. The example token is sufficient for image builds only; replace it with a
  337. real token before using the server. Write tools require the permissions
  338. described in [Requirements](#requirements).
  339. 3. Build the JVM package and the image, then start the server:
  340. ```bash
  341. ./mvnw package
  342. docker compose build
  343. docker compose up -d
  344. ```
  345. 4. Check the container and startup logs:
  346. ```bash
  347. docker compose ps
  348. docker compose logs --tail=100
  349. ```
  350. Connect your MCP client to `http://localhost:8004/mcp` using Streamable HTTP.
  351. The published port is bound to localhost only. For remote access, use an
  352. authenticated reverse proxy; do not expose this unauthenticated server
  353. directly to the internet.
  354. Compose automatically reads `.env`. Exported shell variables take precedence
  355. over values in that file. A non-empty `TOKEN_GITLAB` is required even for
  356. `docker compose build`, because Compose validates the whole configuration.
  357. The local `.env` is excluded from Git and the Docker build context.
  358. Only `.env.example` is intended for publication. The token and GitLab URL
  359. are passed to the running container, not embedded in the image.
  360. ### Update and stop
  361. After updating the source code, rebuild and recreate the service:
  362. ```bash
  363. ./mvnw package
  364. docker compose up -d --build
  365. ```
  366. After changing only `.env`, run `docker compose up -d` to apply the new values.
  367. To follow logs or stop and remove the container and Compose network:
  368. ```bash
  369. docker compose logs -f
  370. docker compose down
  371. ```
  372. ### Optional Docker smoke-test
  373. After building the image, run a real-container protocol check against a local
  374. scripted GitLab API (no real GitLab credentials or writes):
  375. ```bash
  376. ./mvnw test -Dtest=DockerSmokeTest -Ddocker.smoke=true
  377. ```
  378. The test initializes MCP, checks all 33 advertised tools, performs a read and
  379. an issue creation through the packaged application, then removes its container.
  380. Compose uses the stable image name `mcp-gitlab14:local`, regardless of the clone directory.
  381. The test requires Docker and this already built image;
  382. use `-Ddocker.image=your-image` for another image name. It is not a live GitLab
  383. compatibility test and is skipped by the default Maven test run.
  384. ## License
  385. [MIT](LICENSE) — Copyright (c) 2026 Alexander Balashov.
  386. The Apache Maven Wrapper retains its Apache-2.0 license.
  387. See [third-party notices](THIRD_PARTY_NOTICES.md).
  388. ## Contributing and security
  389. See [CONTRIBUTING.md](CONTRIBUTING.md), [SECURITY.md](SECURITY.md), and
  390. [CHANGELOG.md](CHANGELOG.md). Report vulnerabilities privately, not in public issues.

Ratings and comments

Sign in to rate this skill.

Sign in

Free to use. If it’s helped, pass it on.