# GitLab MCP Server

## @anupsahu/gitlab-mcp

MCP (Model Context Protocol) server for GitLab API with OAuth 2.0 PKCE authentication.

## Features

- 🔐 **OAuth 2.0 PKCE Authentication** - Secure authentication with token persistence
- 🔄 **Automatic Token Refresh** - Seamless token renewal with retry logic
- 📁 **Complete GitLab API Coverage** - Merge requests, issues, files, commits, and more
- 💾 **Token Persistence** - Sessions survive server restarts
- 🛡️ **Production Ready** - Clean codebase with comprehensive error handling
- 🔧 **Easy Configuration** - Simple setup with environment variables

## Installation

```bash
npm install -g @anupsahu/gitlab-mcp
```

## Quick Start

### 1. OAuth Authentication (Recommended)

```json
{
  "mcpServers": {
    "gitlab": {
      "command": "npx",
      "args": ["-y", "@anupsahu/gitlab-mcp"],
      "env": {
        "USE_OAUTH": "true",
        "GITLAB_API_URL": "https://gitlab.com/api/v4"
      }
    }
  }
}
```

### 2. Personal Access Token (Alternative)

```json
{
  "mcpServers": {
    "gitlab": {
      "command": "npx",
      "args": ["-y", "@anupsahu/gitlab-mcp"],
      "env": {
        "GITLAB_PERSONAL_ACCESS_TOKEN": "your_gitlab_token",
        "GITLAB_API_URL": "https://gitlab.com/api/v4"
      }
    }
  }
}
```

## OAuth Authentication

The server supports OAuth 2.0 PKCE authentication for secure access to GitLab:

1. **Start the server** with `USE_OAUTH=true`
2. **Authenticate** using the `oauth_login_pkce` tool
3. **Tokens are automatically saved** and persist across restarts
4. **Port requirement**: OAuth callback always uses http://localhost:7171 for compatibility with GitLab's official OAuth app. Ensure port 7171 is free during authentication.

5. **Automatic token refresh** handles expiration seamlessly

### OAuth Tools

- `oauth_login_pkce` - Initiate OAuth authentication
- `oauth_status` - Check authentication status
- `oauth_logout` - Logout and clear tokens

## Configuration

### Environment Variables

| Variable                        | Description                                  | Default                     |
| ------------------------------- | -------------------------------------------- | --------------------------- |
| `USE_OAUTH`                     | Enable OAuth 2.0 authentication              | `false`                     |
| `GITLAB_API_URL`                | GitLab API URL                               | `https://gitlab.com/api/v4` |
| `GITLAB_PERSONAL_ACCESS_TOKEN`  | Personal access token (if not using OAuth)   | -                           |
| `GITLAB_PROJECT_ID`             | Default project ID                           | -                           |
| `GITLAB_ALLOWED_PROJECT_IDS`    | Comma-separated list of allowed project IDs  | -                           |
| `GITLAB_READ_ONLY_MODE`         | Enable read-only mode                        | `false`                     |
| `OAUTH_REDIRECT_PORT_PREFERRED` | Preferred localhost callback port            | `7171`                      |
| `OAUTH_REDIRECT_PORT_RANGE`     | Fallback range for callback port (inclusive) | `7171-7199`                 |

## Available Tools

### Repository Operations

- `search_repositories` - Search for repositories
- `get_repository_tree` - Get repository file tree
- `get_file_contents` - Read file contents
- `create_or_update_file` - Create or update files
- `push_files` - Push multiple files

### Merge Request Operations

- `get_merge_request` - Get merge request details
- `get_merge_request_diffs` - Get merge request changes
- `create_merge_request` - Create new merge request
- `update_merge_request` - Update merge request
- `merge_merge_request` - Merge a merge request

### Issue Operations

- `create_issue` - Create new issue
- `get_issue` - Get issue details
- `update_issue` - Update issue
- `list_issues` - List issues

### Commit Operations

- `list_commits` - List repository commits
- `get_commit` - Get commit details
- `get_commit_diff` - Get commit changes

### Branch Operations

- `create_branch` - Create new branch
- `fork_repository` - Fork repository

## Token Storage

OAuth tokens are automatically saved to:

- **Path**: `~/.config/gitlab-mcp/oauth-config.json`
- **Format**: JSON configuration file
- **Persistence**: Tokens survive server restarts
- **Security**: Automatic token refresh and expiration handling

## Examples

### Authenticate with OAuth

```javascript
// Use the oauth_login_pkce tool
{
  "sessionId": "my-session" // optional
}
```

### Get Merge Request Details

```javascript
{
  "project_id": "12345",
  "merge_request_iid": "123",
  "sessionId": "my-session"
}
```

### Create Issue

```javascript
{
  "project_id": "12345",
  "title": "Bug Report",
  "description": "Description of the issue",
  "sessionId": "my-session"
}
```

## Development

```bash
# Clone repository
git clone https://gitlab.com/anupsahu/gitlab-mcp.git
cd gitlab-mcp

# Install dependencies
npm install

# Build
npm run build

# Run with OAuth
USE_OAUTH=true GITLAB_API_URL=https://gitlab.com/api/v4 node build/index.js
```

## License

MIT License - see [LICENSE](LICENSE) file for details.

## Contributing

1. Fork the repository
2. Create a feature branch
3. Make your changes
4. Add tests if applicable
5. Submit a merge request

## Support

For issues and questions:

- Create an issue in the [GitLab repository](https://gitlab.com/anupsahu/gitlab-mcp)
- Check existing documentation and examples

---

**Built with ❤️ for the MCP ecosystem**