# zereight/gitlab-mcp architecture

> Architecture diagram of the GitHub repository zereight/gitlab-mcp, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-09-29). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/zereight/gitlab-mcp
- Repository: https://github.com/zereight/gitlab-mcp

## Overview

This repository provides a GitLab Model Context Protocol server: an MCP client invokes a selected tool, the server applies authentication and policy, performs GitLab API work, and returns a structured result. Its documented product surface includes project and collaboration management, CI/CD, wiki and release features, filtering/masking, multiple transports, and local or remote OAuth. The tree and sampled excerpts support the main entry, tool registry, OAuth proxy, masking and download subsystems; detailed links among unsampled feature handlers are intentionally omitted.

Main entry points: [`tools/registry.ts`](https://github.com/zereight/gitlab-mcp/blob/main/tools/registry.ts) (Tool Registry), [`index.ts`](https://github.com/zereight/gitlab-mcp/blob/main/index.ts) (MCP Server), [`gitlab-client-pool.ts`](https://github.com/zereight/gitlab-mcp/blob/main/gitlab-client-pool.ts) (HTTP Client Pool), [`oauth-proxy.ts`](https://github.com/zereight/gitlab-mcp/blob/main/oauth-proxy.ts) (OAuth Proxy)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_entry["MCP Runtime"]
  node_server["MCP Server<br/>[index.ts]"]
  node_registry["Tool Registry<br/>[registry.ts]"]
  node_config["Runtime Config<br/>[config.ts]"]
  node_transport["HTTP Transports<br/>[transport-mode.ts]"]
end

subgraph group_security["Auth And Policy"]
  node_auth["Auth Flows<br/>[oauth.ts]"]
  node_oauthproxy["OAuth Proxy<br/>[oauth-proxy.ts]"]
  node_stateless["Stateless OAuth<br/>[index.ts]"]
  node_masking["Response Masking<br/>[engine.ts]"]
end

subgraph group_gitlab["GitLab Operations"]
  node_gitlabapi["GitLab API"]
  node_clientpool["HTTP Client Pool"]
end

subgraph group_features["Product Capabilities"]
  node_toolsets["Project And Issues<br/>[registry.ts]"]
  node_mr["Merge Requests<br/>[registry.ts]"]
  node_cicd["CI/CD<br/>[registry.ts]"]
  node_wiki["Wiki And Releases<br/>[registry.ts]"]
  node_graphql["GraphQL Tools<br/>[registry.ts]"]
  node_downloads["Download Proxy<br/>[proxy.ts]"]
end

subgraph group_support["Runtime Services"]
  node_metrics["Metrics<br/>[metrics.ts]"]
end

node_client(("MCP Client"))
node_externalgitlab[("GitLab Instance")]

node_client -->|"invokes tools"| node_server
node_server -->|"registers tools"| node_registry
node_server -->|"loads settings"| node_config
node_server -->|"selects transport"| node_transport
node_registry -->|"exposes tools"| node_toolsets
node_registry -->|"exposes tools"| node_mr
node_registry -->|"exposes tools"| node_cicd
node_registry -->|"exposes tools"| node_wiki
node_registry -->|"exposes tools"| node_graphql
node_registry -->|"uses credentials"| node_auth
node_registry -->|"masks responses"| node_masking
node_registry -->|"uses clients"| node_clientpool
node_clientpool -->|"dispatches requests"| node_externalgitlab
node_externalgitlab -->|"returns responses"| node_clientpool
node_auth -.->|"enables proxy flow"| node_oauthproxy
node_oauthproxy -.->|"encodes tokens"| node_stateless
node_oauthproxy -.->|"exchanges tokens"| node_externalgitlab
node_server -->|"registers endpoint"| node_downloads
node_downloads -->|"gets dispatcher"| node_clientpool
node_downloads -->|"streams downloads"| node_externalgitlab
node_server -->|"reports metrics"| node_metrics

click node_server "https://github.com/zereight/gitlab-mcp/blob/main/index.ts"
click node_registry "https://github.com/zereight/gitlab-mcp/blob/main/tools/registry.ts"
click node_config "https://github.com/zereight/gitlab-mcp/blob/main/config.ts"
click node_auth "https://github.com/zereight/gitlab-mcp/blob/main/oauth.ts"
click node_oauthproxy "https://github.com/zereight/gitlab-mcp/blob/main/oauth-proxy.ts"
click node_stateless "https://github.com/zereight/gitlab-mcp/blob/main/stateless/index.ts"
click node_masking "https://github.com/zereight/gitlab-mcp/blob/main/masking/engine.ts"
click node_toolsets "https://github.com/zereight/gitlab-mcp/blob/main/tools/registry.ts"
click node_mr "https://github.com/zereight/gitlab-mcp/blob/main/tools/registry.ts"
click node_cicd "https://github.com/zereight/gitlab-mcp/blob/main/tools/registry.ts"
click node_wiki "https://github.com/zereight/gitlab-mcp/blob/main/tools/registry.ts"
click node_graphql "https://github.com/zereight/gitlab-mcp/blob/main/tools/registry.ts"
click node_downloads "https://github.com/zereight/gitlab-mcp/blob/main/downloads/proxy.ts"
click node_clientpool "https://github.com/zereight/gitlab-mcp/blob/main/gitlab-client-pool.ts"
click node_transport "https://github.com/zereight/gitlab-mcp/blob/main/server/transport-mode.ts"
click node_metrics "https://github.com/zereight/gitlab-mcp/blob/main/server/metrics.ts"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_server,node_registry,node_config,node_transport,node_client toneBlue
class node_auth,node_oauthproxy,node_stateless,node_masking,node_externalgitlab toneAmber
class node_gitlabapi,node_clientpool toneMint
class node_toolsets,node_mr,node_cicd,node_wiki,node_graphql,node_downloads toneRose
class node_metrics toneIndigo
```

## Components

### MCP Runtime

- [MCP Server](https://github.com/zereight/gitlab-mcp/blob/main/index.ts): `index.ts`
- [Tool Registry](https://github.com/zereight/gitlab-mcp/blob/main/tools/registry.ts): `tools/registry.ts`
- [Runtime Config](https://github.com/zereight/gitlab-mcp/blob/main/config.ts): `config.ts`
- [HTTP Transports](https://github.com/zereight/gitlab-mcp/blob/main/server/transport-mode.ts): `server/transport-mode.ts`

### Auth And Policy

- [Auth Flows](https://github.com/zereight/gitlab-mcp/blob/main/oauth.ts): `oauth.ts`
- [OAuth Proxy](https://github.com/zereight/gitlab-mcp/blob/main/oauth-proxy.ts): `oauth-proxy.ts`
- [Stateless OAuth](https://github.com/zereight/gitlab-mcp/blob/main/stateless/index.ts): `stateless/index.ts`
- [Response Masking](https://github.com/zereight/gitlab-mcp/blob/main/masking/engine.ts): `masking/engine.ts`

### GitLab Operations

- **GitLab API**
- [HTTP Client Pool](https://github.com/zereight/gitlab-mcp/blob/main/gitlab-client-pool.ts): `gitlab-client-pool.ts`

### Product Capabilities

- [Project And Issues](https://github.com/zereight/gitlab-mcp/blob/main/tools/registry.ts): `tools/registry.ts`
- [Merge Requests](https://github.com/zereight/gitlab-mcp/blob/main/tools/registry.ts): `tools/registry.ts`
- [CI/CD](https://github.com/zereight/gitlab-mcp/blob/main/tools/registry.ts): `tools/registry.ts`
- [Wiki And Releases](https://github.com/zereight/gitlab-mcp/blob/main/tools/registry.ts): `tools/registry.ts`
- [GraphQL Tools](https://github.com/zereight/gitlab-mcp/blob/main/tools/registry.ts): `tools/registry.ts`
- [Download Proxy](https://github.com/zereight/gitlab-mcp/blob/main/downloads/proxy.ts): `downloads/proxy.ts`

### Runtime Services

- [Metrics](https://github.com/zereight/gitlab-mcp/blob/main/server/metrics.ts): `server/metrics.ts`

### Other components

- **MCP Client**
- **GitLab Instance**

## Connections

- MCP Client → MCP Server: invokes tools
- MCP Server → Tool Registry: registers tools
- MCP Server → Runtime Config: loads settings
- MCP Server → HTTP Transports: selects transport
- Tool Registry → Project And Issues: exposes tools
- Tool Registry → Merge Requests: exposes tools
- Tool Registry → CI/CD: exposes tools
- Tool Registry → Wiki And Releases: exposes tools
- Tool Registry → GraphQL Tools: exposes tools
- Tool Registry → Auth Flows: uses credentials
- Tool Registry → Response Masking: masks responses
- Tool Registry → HTTP Client Pool: uses clients
- HTTP Client Pool → GitLab Instance: dispatches requests
- GitLab Instance → HTTP Client Pool: returns responses
- Auth Flows → OAuth Proxy: enables proxy flow
- OAuth Proxy → Stateless OAuth: encodes tokens
- OAuth Proxy → GitLab Instance: exchanges tokens
- MCP Server → Download Proxy: registers endpoint
- Download Proxy → HTTP Client Pool: gets dispatcher
- Download Proxy → GitLab Instance: streams downloads
- MCP Server → Metrics: reports metrics