GitLab Jira Context MCP

A local Model Context Protocol (MCP) server that connects GitLab project and merge-request context with Jira work tracking, Confluence pages, and Grafana dashboards. Jira comments and worklogs can be added only with explicit confirmation.

The server uses stdio and runs on your machine. It sends requests only to the service URLs that you configure locally.

Architecture

flowchart LR
  Client[VS Code / MCP Client] <-->|stdio| Server[GitLab Jira Context MCP]
  Server -->|REST API| GitLab[GitLab]
  Server -->|REST API| Jira[Jira]
  Server -. optional REST API .-> Confluence[Confluence]
  Server -. optional REST API .-> Grafana[Grafana]
  Config[Local .env] -. credentials and URLs .-> Server

The server never exposes an HTTP endpoint or persists service data. Tokens stay in your local .env file or process environment.

Related MCP server: gitlab-mcp

Included Tools

GitLab, Confluence, and Grafana tools are read-only. Jira mutations require an explicit confirm: true input and use the permissions of the configured Jira token.

Jira search, comments, and worklogs return the service's pagination metadata. When total exceeds the number of returned entries, call the same tool with a later startAt value. jira_add_worklog accepts Jira duration syntax such as 1h 30m and an optional ISO 8601 started timestamp.

Repository Structure

gitlab-jira-context-mcp/
├── src/
│   ├── client.ts       # HTTP clients, authentication, and request helpers
│   └── server.ts       # MCP tool registration and input schemas
├── test/
│   └── client.test.ts  # Focused helper and request-payload tests
├── .env.example        # Neutral local configuration template
├── package.json        # Scripts and dependencies
└── tsconfig.json       # TypeScript configuration

Requirements

• Node.js 20 or newer

• An MCP client with stdio server support, such as Visual Studio Code with GitHub Copilot

• A GitLab personal access token with access to the projects you need

• A Jira Server or Data Center personal access token

• Optional: a Confluence Server or Data Center personal access token

• Optional: a Grafana service account token with dashboard read access

Quick Start

1. Clone the repository and install dependencies.

   git clone https://github.com/jagarkarlo/gitlab-jira-context-mcp.git
   cd gitlab-jira-context-mcp
   npm install
   npm test
   npm run build

2. Create your local configuration.

   cp .env.example .env

   Set GITLAB_BASE_URL, GITLAB_TOKEN, JIRA_BASE_URL, and JIRA_API_TOKEN. Confluence and Grafana are optional; set both variables in either integration's pair to enable its tools. Keep .env local; it is ignored by Git.

3. Register the compiled server in your MCP client. In VS Code, run MCP: Open User Configuration and add this entry to the servers object. Replace /absolute/path/to with the cloned repository path.

   {
     "servers": {
       "gitlab-jira-context": {
         "type": "stdio",
         "command": "node",
         "args": [
           "/absolute/path/to/gitlab-jira-context-mcp/dist/server.js"
         ]
       }
     }
   }

4. Restart the server from MCP: List Servers or reload VS Code.

Security

• The server reads credentials only from the local .env file or process environment.

• Use tokens with the smallest access scope that supports your intended requests.

• Review the configured service URLs before starting the server.

• Do not place credentials in source files, MCP configuration, issue comments, or commits.

• Verify the issue key, work duration, and content before setting confirm: true for a Jira write.

Configuration Boundaries

Development

Run the checks before committing changes:

npm test
npm run build
git diff --check

src/client.ts contains the HTTP and response-handling helpers. src/server.ts registers the MCP tools and their input schemas. Tests cover the shared client helpers; add focused tests when changing behavior.

Roadmap

Future releases can add GitLab merge-request discussions and project search, while retaining explicit confirmation for every write operation.

License

This project is licensed under the MIT License.