mcp-gitlab-jira
Enables interaction with GitLab instances, allowing users to manage projects, merge requests (view details, add comments, assign reviewers), access file content, list releases, and view user information.
Provides comprehensive Jira ticket management capabilities, including retrieving ticket details, adding comments, searching with JQL, creating new tickets, transitioning tickets between statuses, and updating ticket fields.
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type
@followed by the MCP server name and your instructions, e.g., "@mcp-gitlab-jira list open merge requests for project 'web-app'"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
MCP GitLab Jira Server
A Model Context Protocol (MCP) server for GitLab and Jira integration. This server allows AI agents like gemini-cli to interact with your GitLab and Jira instances.
Features
GitLab
Projects: List all accessible projects or filter them by name.
Merge Requests: List merge requests for a project, get detailed information (including diffs), add comments, and assign reviewers.
Pipeline/CI/CD: Get pipeline status, trigger/retry/cancel pipelines, get job details and logs.
Branch Management: List, create, delete branches and get branch details.
Issue Management: Create, list, update, close issues and manage comments.
Files: Get the content of a specific file at a given SHA.
Releases: List all releases for a project or filter them since a specific version.
Users: List project members, get a user's ID by username, and get user activities.
Jira
Tickets: Get detailed information about a ticket, get comments, add comments, search for tickets using JQL, create new tickets, get available transitions, update tickets, and transition tickets to a new status.
Project Management: Get all projects, project details, components, and versions.
Related MCP server: MCP Jira & Confluence Server
Setup
Prerequisites
Node.js 18+
GitLab Personal Access Token with API access
Jira API Token
Access to a GitLab instance (on-premise or GitLab.com)
Access to a Jira instance
Installation
Install the package globally:
npm i -g mcp-gitlab-jiraSet up environment variables:
# GitLab export GITLAB_URL="https://your-gitlab-instance.com" export GITLAB_ACCESS_TOKEN="your-personal-access-token" # Jira export ATLASSIAN_SITE_NAME="your-atlassian-site-name" export ATLASSIAN_USER_EMAIL="your-email@example.com" export ATLASSIAN_API_TOKEN="your-jira-api-token"Test the server manually:
# Test that the server starts without errors echo '{"jsonrpc": "2.0", "id": 1, "method": "tools/list", "params": {}}' | mcp-gitlab-jiraThe server should start and log "GitLab/Jira MCP server started" to stderr.
Using with MCP Clients
Configuration for gemini-cli or other MCP clients
Create or update your MCP configuration file (usually ~/.mcp/config.json or similar):
{
"mcpServers": {
"gitlab-jira-mcp": {
"command": "mcp-gitlab-jira",
"env": {
"GITLAB_URL": "https://your-gitlab-instance.com",
"GITLAB_ACCESS_TOKEN": "your-personal-access-token",
"ATLASSIAN_SITE_NAME": "your-atlassian-site-name",
"ATLASSIAN_USER_EMAIL": "your-email@example.com",
"ATLASSIAN_API_TOKEN": "your-jira-api-token"
}
}
}
}Running with Docker
You can also run this MCP server in a Docker container using the pre-built image from Docker Hub.
Available Docker Images
The Docker images are automatically built and published to Docker Hub for each release:
Latest release:
hainanzhao/mcp-gitlab-jira:latestSpecific versions:
hainanzhao/mcp-gitlab-jira:v0.1.2,hainanzhao/mcp-gitlab-jira:v0.1.1, etc.View all available tags: Docker Hub - mcp-gitlab-jira
The images are built for multiple architectures: linux/amd64 and linux/arm64 (Apple Silicon compatible).
Usage
Pull and run the Docker container:
docker run -d --name mcp-gitlab-jira-container \ -e GITLAB_URL="https://your-gitlab-instance.com" \ -e GITLAB_ACCESS_TOKEN="your-personal-access-token" \ -e ATLASSIAN_SITE_NAME="your-atlassian-site-name" \ -e ATLASSIAN_USER_EMAIL="your-email@example.com" \ -e ATLASSIAN_API_TOKEN="your-jira-api-token" \ hainanzhao/mcp-gitlab-jira:latestAlternative: Run without persistent container (one-time execution):
docker run --rm -i \ -e GITLAB_URL="https://your-gitlab-instance.com" \ -e GITLAB_ACCESS_TOKEN="your-personal-access-token" \ -e ATLASSIAN_SITE_NAME="your-atlassian-site-name" \ -e ATLASSIAN_USER_EMAIL="your-email@example.com" \ -e ATLASSIAN_API_TOKEN="your-jira-api-token" \ hainanzhao/mcp-gitlab-jira:latest
Using with MCP Clients (Docker)
You have two options for using the Docker container with MCP clients:
Option 1: Using a persistent container (recommended)
First, start the container as shown above, then update your MCP configuration file. The env block is empty because the necessary environment variables are passed directly to the container using the -e flag in the docker run command.
{
"mcpServers": {
"gitlab-jira-mcp": {
"command": "docker",
"args": ["exec", "-i", "mcp-gitlab-jira-container", "npm", "start"],
"env": {}
}
}
}Option 2: Using one-time execution
This runs a new container for each MCP session:
{
"mcpServers": {
"gitlab-jira-mcp": {
"command": "docker",
"args": [
"run", "--rm", "-i",
"-e", "GITLAB_URL=https://your-gitlab-instance.com",
"-e", "GITLAB_ACCESS_TOKEN=your-personal-access-token",
"-e", "ATLASSIAN_SITE_NAME=your-atlassian-site-name",
"-e", "ATLASSIAN_USER_EMAIL=your-email@example.com",
"-e", "ATLASSIAN_API_TOKEN=your-jira-api-token",
"hainanzhao/mcp-gitlab-jira:latest"
],
"env": {}
}
}
}Available Tools
GitLab Tools
Core GitLab Tools
gitlab_get_merge_request_details: Fetches detailed information about a GitLab Merge Request, including file diffs.gitlab_get_file_content: Fetches the content of a specific file at a given SHA in a GitLab project.gitlab_add_comment_to_merge_request: Adds a comment to a GitLab Merge Request. Can be a general comment, a reply to an existing discussion, or an inline comment on a specific line.gitlab_list_merge_requests: Lists merge requests for a given GitLab project.gitlab_assign_reviewers_to_merge_request: Assigns reviewers to a GitLab Merge Request.gitlab_list_project_members: Lists all members (contributors) of a given GitLab project.gitlab_list_project_members_by_project_name: Lists all members (contributors) of a given GitLab project by project name.gitlab_list_projects_by_name: Filters GitLab projects by name using a fuzzy, case-insensitive match.gitlab_list_all_projects: Lists all accessible GitLab projects.gitlab_list_all_releases: Fetches releases for a given GitLab project.gitlab_list_releases_since_version: Filters releases for a given GitLab project since a specific version.gitlab_get_user_id_by_username: Retrieves the GitLab user ID for a given username.gitlab_get_user_activities: Fetches activities for a given GitLab user by their username, optionally filtered by date.
GitLab Pipeline/CI/CD Tools
gitlab_get_project_pipelines: Gets pipelines for a GitLab project, optionally filtered by branch/ref.gitlab_get_merge_request_pipelines: Gets pipelines for a specific GitLab Merge Request.gitlab_get_pipeline_details: Gets detailed information about a specific pipeline.gitlab_get_pipeline_jobs: Gets jobs for a specific pipeline.gitlab_get_job_logs: Gets logs for a specific job.gitlab_trigger_pipeline: Triggers a new pipeline for a specific branch/ref.gitlab_retry_pipeline: Retries a failed pipeline.gitlab_cancel_pipeline: Cancels a running pipeline.
GitLab Branch Management Tools
gitlab_list_branches: Lists all branches in a GitLab project.gitlab_create_branch: Creates a new branch in a GitLab project.gitlab_delete_branch: Deletes a branch from a GitLab project.gitlab_get_branch_details: Gets detailed information about a specific branch.
GitLab Issue Management Tools
gitlab_list_project_issues: Lists issues in a GitLab project.gitlab_get_issue_details: Gets detailed information about a specific GitLab issue.gitlab_create_issue: Creates a new issue in a GitLab project.gitlab_update_issue: Updates an existing GitLab issue.gitlab_close_issue: Closes a GitLab issue.gitlab_add_comment_to_issue: Adds a comment to a GitLab issue.gitlab_get_issue_comments: Gets comments for a GitLab issue.
Jira Tools
Core Jira Tools
jira_get_ticket_details: Fetches comprehensive information about a Jira ticket with flattened fields, including all custom fields with user-friendly names. Automatically filters out empty values and less useful fields (attachments, avatars). Returns both system and custom fields in a clean, flat structure.jira_get_ticket_comments: Fetches comments for a Jira ticket.jira_add_comment_to_ticket: Adds a comment to a Jira ticket.jira_search_tickets_by_jql: Searches for Jira tickets using a JQL (Jira Query Language) string.jira_create_ticket: Creates a new Jira ticket with given fields.jira_get_available_transitions: Fetches available transitions for a Jira ticket.jira_update_ticket: Updates a Jira ticket summary, description, labels.jira_update_custom_fields: Updates custom fields on a Jira ticket.jira_update_ticket_priority: Updates the priority value for a Jira ticket. Automatically finds the priority custom field (case-insensitive search for "Priority" or "priority"), fetches the allowed values for that field, and matches the provided priority name using fuzzy string matching. Accepts values like "Critical", "High", "Medium", "Low", etc., and will find the best match from the predefined options.jira_update_ticket_sprint: Updates the sprint value for a Jira ticket. Automatically finds the sprint custom field (case-insensitive search for "Sprint" or "sprint"), fetches available sprints from the project's boards, and matches the provided sprint name using fuzzy string matching. Accepts values like "Sprint 1", "Bug Fix Sprint", etc., and will find the best match from active and future sprints in the project.jira_transition_ticket: Transitions a Jira ticket to a new status.jira_get_all_fields: Fetches the list of all fields from Jira.
Jira Project Management Tools
jira_get_all_projects: Gets all accessible Jira projects.jira_get_project_details: Gets detailed information about a specific Jira project.jira_get_project_components: Gets components for a Jira project.jira_get_project_versions: Gets versions for a Jira project.
Troubleshooting
Common Issues
"Cannot find module" errors: If you are developing locally, make sure you've run
npm installandnpm run build.Authentication errors: Verify your
GITLAB_ACCESS_TOKEN,ATLASSIAN_USER_EMAIL, andATLASSIAN_API_TOKENhave the necessary permissions.Connection errors: Ensure your
GITLAB_URLandATLASSIAN_SITE_NAMEare correct and accessible.Server not responding: Check that the MCP server process is running and the path in your config is correct.
Debug Mode
To see detailed logs, you can run the server directly:
export GITLAB_URL="your-url"
export GITLAB_ACCESS_TOKEN="your-token"
export ATLASSIAN_SITE_NAME="your-atlassian-site-name"
export ATLASSIAN_USER_EMAIL="your-email@example.com"
export ATLASSIAN_API_TOKEN="your-jira-api-token"
mcp-gitlab-jiraDevelopment
For development, clone the repository and install the dependencies.
npm install
npm run buildLocal Docker Development
To test the Docker build locally before pushing:
# Build and test the Docker image locally
./scripts/build-docker-local.shThis script will build the Docker image and run basic tests to ensure it works correctly.
For maintainers: See Docker Setup Guide for information about setting up automated Docker Hub publishing.
Project Structure
src/index.ts: Main MCP server implementationsrc/gitlab.service.ts: GitLab API clientsrc/gitlab.ts: GitLab type definitionssrc/jira.service.ts: Jira API clientsrc/jira.ts: Jira type definitionsdist/: Compiled JavaScript output
Adding New Features
Add new methods to the
GitLabServiceorJiraServiceclass.Define new tools in the
allToolsarray inindex.ts.Add a corresponding case in the tool handler in
index.ts.Rebuild with
npm run build.
License
ISC
Available Tools
32 toolsgitlab_add_comment_to_issueC
Adds a comment to a GitLab issue.
Inputs: projectPath (required), issueIid (required), body (required).
gitlab_add_comment_to_merge_requestB
Adds a comment to a GitLab Merge Request. Can be a general comment, a reply to an existing discussion, or an inline comment on a specific line.
Inputs: mrUrl (required), commentBody (required), discussionId, position.
gitlab_assign_reviewers_to_merge_requestC
Assigns reviewers to a GitLab Merge Request.
Inputs: mrUrl (required), reviewerIds (required).
gitlab_cancel_pipelineC
Cancels a running pipeline.
Inputs: projectPath (required), pipelineId (required).
gitlab_close_issueC
Closes a GitLab issue.
Inputs: projectPath (required), issueIid (required).
gitlab_create_branchC
Creates a new branch in a GitLab project.
Inputs: projectPath (required), branchName (required), ref (required).
gitlab_create_issueC
Creates a new issue in a GitLab project.
Inputs: projectPath (required), title (required), description, labels, +1 more.
gitlab_delete_branchC
Deletes a branch from a GitLab project.
Inputs: projectPath (required), branchName (required).
gitlab_get_branch_detailsC
Gets detailed information about a specific branch.
Inputs: projectPath (required), branchName (required).
gitlab_get_file_contentB
Fetches the content of a specific file at a given SHA in a GitLab project.
Inputs: mrUrl (required), filePath (required), sha (required).
gitlab_get_issue_commentsC
Gets comments for a GitLab issue.
Inputs: projectPath (required), issueIid (required).
gitlab_get_issue_detailsC
Gets detailed information about a specific GitLab issue.
Inputs: projectPath (required), issueIid (required).
gitlab_get_job_logsC
Gets logs for a specific job.
Inputs: projectPath (required), jobId (required).
gitlab_get_merge_request_detailsB
Fetches detailed information about a GitLab Merge Request, including file diffs.
Inputs: mrUrl (required).
gitlab_get_merge_request_pipelinesC
Gets pipelines for a specific GitLab Merge Request.
Inputs: mrUrl (required).
gitlab_get_pipeline_detailsB
Gets detailed information about a specific pipeline.
Inputs: projectPath (required), pipelineId (required).
gitlab_get_pipeline_jobsC
Gets jobs for a specific pipeline.
Inputs: projectPath (required), pipelineId (required).
gitlab_get_project_pipelinesC
Gets pipelines for a GitLab project, optionally filtered by branch/ref.
Inputs: projectPath (required), ref.
gitlab_get_user_activitiesC
Fetches activities for a given GitLab user by their username, optionally filtered by date.
Inputs: username (required), sinceDate.
gitlab_get_user_id_by_usernameB
Retrieves the GitLab user ID for a given username.
Inputs: username (required).
gitlab_list_all_projectsA
Lists all accessible GitLab projects. (Try to use list_projects_by_name as it is more efficient)
Inputs: no named parameters.
gitlab_list_all_releasesC
Fetches releases for a given GitLab project.
Inputs: projectPath (required).
gitlab_list_branchesC
Lists all branches in a GitLab project.
Inputs: projectPath (required).
gitlab_list_merge_requestsC
Lists merge requests for a given GitLab project.
Inputs: projectPath (required).
gitlab_list_project_issuesC
Lists issues in a GitLab project.
Inputs: projectPath (required), state.
gitlab_list_project_membersC
Lists all members (contributors) of a given GitLab project.
Inputs: mrUrl (required).
gitlab_list_project_members_by_project_nameC
Lists all members (contributors) of a given GitLab project by project name.
Inputs: projectName (required).
gitlab_list_projects_by_nameB
Filters GitLab projects by name using a fuzzy, case-insensitive match.
Inputs: projectName (required).
gitlab_list_releases_since_versionC
Filters releases for a given GitLab project since a specific version.
Inputs: projectName (required), sinceVersion (required).
gitlab_retry_pipelineC
Retries a failed pipeline.
Inputs: projectPath (required), pipelineId (required).
gitlab_trigger_pipelineC
Triggers a new pipeline for a specific branch/ref.
Inputs: projectPath (required), ref (required), variables.
gitlab_update_issueC
Updates an existing GitLab issue.
Inputs: projectPath (required), issueIid (required), updates (required).
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
TDQS
Scored across 32 tools
Most tools have distinct purposes targeting specific GitLab resources and actions, with clear boundaries like gitlab_create_issue vs. gitlab_update_issue. However, some overlap exists between gitlab_list_project_members and gitlab_list_project_members_by_project_name, which could cause confusion as they serve similar functions with minor differences in input parameters.
All tools follow a consistent gitlab_verb_noun pattern with snake_case throughout, such as gitlab_get_issue_details and gitlab_trigger_pipeline. This predictability makes it easy for agents to understand and navigate the toolset without naming conflicts or style variations.
With 32 tools, the count is borderline high for a GitLab-focused server, as it may feel heavy and potentially overwhelming for agents. While it covers many aspects, it approaches the upper limit where efficiency could be impacted, though it remains within a reasonable scope for comprehensive GitLab operations.
The toolset provides extensive coverage of GitLab's domain, including CRUD operations for issues, merge requests, branches, pipelines, and more, with no obvious gaps. It supports full lifecycle management from creation to updates and deletions, ensuring agents can handle most workflows without dead ends.
Maintenance
Related MCP Connectors
A comprehensive Model Context Protocol (MCP) server that enables AI assistants to interact with yo…
The Mercado Pago MCP Server implements the Model Context Protocol to provide AI agents and LLMs with access to Mercado Pago's APIs and tools within compatible development environments. It acts as an intermediary that translates Mercado Pago resources into executable functions (tools) that AI applications can invoke to perform actions and automate flows. The server simplifies integration, enables using documentation to implement or improve code, and optimizes operations through natural language interactions without manual implementations.
Go MCP server for GitLab: 2 dynamic tools reach 1000+ REST/GraphQL actions. Free/CE, no paid tier.
MCP server unifying ERPs, CRMs, APIs and knowledge base for Claude, ChatGPT and Gemini.
Related MCP Servers
- -licenseNot gradedqualityNot gradedmaintenanceA Model Context Protocol server that enables AI assistants to interact with GitLab repositories, allowing tasks like managing merge requests, searching projects, and creating comments through RESTful API integration.77 npm2-
- AlicenseBqualityDmaintenanceA Model Context Protocol server that integrates with Atlassian's Jira and Confluence, enabling AI assistants to interact with these tools directly through features like issue management, page creation, and content search.131MIT
- AlicenseNot gradedqualityDmaintenanceA clean and focused Model Context Protocol (MCP) server that provides seamless integration between AI assistants and Jira, enabling natural language interaction with your Jira projects, issues, and workflows.5MIT
- AlicenseNot gradedqualityDmaintenanceA Model Context Protocol server for GitLab integration, enabling AI assistants to manage projects, merge requests, pipelines, issues, releases, and more.MIT