contextloom-mcp

Renamed from gitlab-jira-context-mcp; GitHub redirects the old URL.

A local Model Context Protocol (MCP) server that connects GitLab project and merge-request context with Jira work tracking, Confluence pages, Grafana dashboards, and optional GitHub repository context. Jira comments, worklogs, and GitHub file changes require 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[contextloom-mcp]
  Server -->|REST API| GitLab[GitLab]
  Server -->|REST API| Jira[Jira]
  Server -. optional REST API .-> Confluence[Confluence]
  Server -. optional REST API .-> Grafana[Grafana]
  Server -. optional REST API .-> GitHub[GitHub]
  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, Grafana, and GitHub read tools are read-only. Jira mutations and GitHub file writes require an explicit confirm: true input and use the permissions of the configured 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

contextloom-mcp/
├── src/
│   ├── client.ts       # HTTP clients, authentication, and request helpers
│   ├── proxy.ts        # Proxy-aware fetch dispatcher shared by every client
│   ├── config.ts       # GitLab instance resolution (single host or GITLAB_INSTANCES)
│   └── 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 (or several, via GITLAB_INSTANCES)

• 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

• Optional: a GitHub fine-grained personal access token; repository metadata and file reads need read access, while github_create_or_update_file needs repository contents write access

Quick Start

1. Clone the repository and install dependencies.

   git clone https://github.com/jagarkarlo/contextloom-mcp.git
   cd contextloom-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. Use GITLAB_INSTANCES instead of the single GitLab pair to talk to more than one host. Confluence and Grafana are optional; set both variables in either integration's pair to enable its tools. Set GITHUB_TOKEN to enable GitHub tools; GITHUB_API_BASE_URL is optional for GitHub Enterprise Server. Set HTTPS_PROXY/NO_PROXY only if reaching one of these hosts needs a corporate proxy. 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": {
       "contextloom": {
         "type": "stdio",
         "command": "node",
         "args": [
           "/absolute/path/to/contextloom-mcp/dist/server.js"
         ]
       }
     }
   }

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

Multiple GitLab hosts

Every gitlab_* tool accepts an optional instance argument. With a single GITLAB_BASE_URL/GITLAB_TOKEN pair it is unnecessary. With GITLAB_INSTANCES set to a JSON array of { "name", "baseUrl", "token" } objects, pass instance to pick one; omitting it uses the first entry.

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.

• Use a fine-grained GitHub token scoped only to the repositories and contents permissions you need.

• Read the existing file with github_get_file_content and pass its returned SHA when updating a GitHub file.

• A corporate proxy dispatcher (via undici) is only attached for a host when HTTPS_PROXY/HTTP_PROXY is set and that host is not covered by NO_PROXY — Node's global fetch does not read those variables on its own, unlike curl.

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/proxy.ts holds the proxy-aware fetch dispatcher shared by every client. src/config.ts resolves one or more GitLab instances from the environment. 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.