# gitlab-mcp-server

An MCP (Model Context Protocol) server for a **self-hosted GitLab** instance, focused on browsing **projects and repositories**. It exposes read-only tools so an MCP client (Claude desktop, Claude Code, etc.) can list projects, inspect branches and commits, browse the file tree, and read file contents.

## Tools

| Tool | Purpose |
|------|---------|
| `gitlab_list_projects` | List / search projects, filter by owned or membership |
| `gitlab_get_project` | Detailed info for one project (default branch, clone URLs, etc.) |
| `gitlab_list_branches` | List repository branches with their tip commit |
| `gitlab_list_commits` | List commits, filter by ref / path / date range |
| `gitlab_get_commit` | Full details and line-change stats for one commit |
| `gitlab_list_repository_tree` | Browse files & directories at a path (optionally recursive) |
| `gitlab_get_file` | Read decoded contents of a single file |

All tools are read-only and support pagination (`page`, `per_page`) and a `response_format` of `markdown` (default) or `json`.

## Requirements

- Node.js 18+
- A GitLab Personal Access Token (PAT)

## Setup

```bash
npm install
npm run build
```

### Create a Personal Access Token

In GitLab: **User Settings → Access Tokens**. Create a token with these scopes:

- `read_api` — required for listing projects, branches and commits
- `read_repository` — required for the repository tree and file contents

Keep the token secret. It is read from an environment variable, never stored in code.

### Configuration

| Variable | Required | Description |
|----------|----------|-------------|
| `GITLAB_BASE_URL` | yes | Base URL of your instance, e.g. `https://gitlab.example.com` (no `/api/v4` suffix needed) |
| `GITLAB_TOKEN` | yes | Your Personal Access Token |
| `TRANSPORT` | no | `stdio` (default) or `http` |
| `PORT` | no | Port for `http` transport (default `3000`) |

## Running

```bash
# stdio (default — for local MCP clients)
GITLAB_BASE_URL=https://gitlab.example.com GITLAB_TOKEN=glpat-xxxx npm start

# HTTP transport (binds to 127.0.0.1)
TRANSPORT=http PORT=3000 GITLAB_BASE_URL=https://gitlab.example.com GITLAB_TOKEN=glpat-xxxx npm start
```

## Connecting to an MCP client

Most desktop clients use a JSON config block. Point it at the built entry point and supply the environment variables:

```json
{
  "mcpServers": {
    "gitlab": {
      "command": "node",
      "args": ["/absolute/path/to/gitlab-mcp-server/dist/index.js"],
      "env": {
        "GITLAB_BASE_URL": "https://gitlab.example.com",
        "GITLAB_TOKEN": "glpat-xxxxxxxxxxxxxxxxxxxx"
      }
    }
  }
}
```

Replace the path with the absolute path to `dist/index.js` on your machine, and fill in your instance URL and token. Restart the client to pick up the new server.

## Project structure

```
gitlab-mcp-server/
├── package.json
├── tsconfig.json
├── README.md
└── src/
    ├── index.ts            # Entry point, transport selection, env validation
    ├── constants.ts        # Config readers and limits
    ├── types.ts            # GitLab resource interfaces
    ├── schemas/common.ts   # Shared Zod schema fragments
    ├── services/client.ts  # Authenticated API client, pagination, errors
    └── tools/projects.ts   # Tool definitions and registration
```

## Identifying projects

Wherever a `project_id` is required, you can pass either:

- the numeric project ID, e.g. `42`, or
- the namespace path, e.g. `mygroup/myrepo` (the server URL-encodes it for you).

## Notes

- This server only performs **read** operations. It never creates, edits, or deletes anything in GitLab.
- Large file or list responses are truncated at 25,000 characters; use pagination or narrower filters to retrieve more.
- For development with auto-reload: `npm run dev`.