npm package: @inteli-tools/gitlab-mcp
Description: MCP server for Inteli GitLab instance - groups, projects, boards, and repository auditing
Author: jrcf
Latest version: 1.0.0

# @inteli-tools/gitlab-mcp

A production-ready [MCP](https://modelcontextprotocol.io/) server for Inteli's GitLab instance (`git.inteli.edu.br`). Provides 40+ tools that let AI assistants discover, read, and manage GitLab projects, groups, boards, issues, merge requests, pipelines, commits, and perform comprehensive repository auditing.

[![Node CI](https://img.shields.io/github/actions/workflow/status/Inteli-Tools/Gitlab-MCP/ci.yml?branch=main)](https://github.com/Inteli-Tools/Gitlab-MCP/actions)
[![npm](https://img.shields.io/npm/v/@inteli-tools/gitlab-mcp)](https://www.npmjs.com/package/@inteli-tools/gitlab-mcp)
[![License](https://img.shields.io/npm/l/@inteli-tools/gitlab-mcp)](LICENSE)

## Highlights

- **Groups & Projects** — Discover, list, and manage Inteli projects and groups
- **Boards & Issues** — Access project boards, create and manage issues
- **Merge Requests** — List, create, and merge request operations
- **Commits & History** — Browse commits, diffs, and repository history
- **Pipelines** — Monitor CI/CD pipeline status and job outputs
- **Repository Auditing** — Comprehensive repository analysis and auditing tools
- **Search** — Full-text search across GitLab resources
- **Simple Integration** — Works with Claude Desktop, VS Code, Cursor, and more
- **Personal Access Token Auth** — Easy authentication with GitLab PAT

## Installation

```bash
npm install -g @inteli-tools/gitlab-mcp
```

Or use directly without global install:

```bash
npx @inteli-tools/gitlab-mcp
```

## Quick Start

### 1. Get Your GitLab Token

1. Go to https://git.inteli.edu.br/
2. Settings → Access Tokens → Create new token
3. Scopes: `api`, `read_repository` (read-only recommended)
4. Copy the token

### 2. Configure for VS Code

Edit VS Code settings (`Cmd+Shift+P` → "Preferences: Open User Settings (JSON)"):

```json
{
  "mcpServers": {
    "gitlab-inteli": {
      "command": "npx",
      "args": ["@inteli-tools/gitlab-mcp@latest"],
      "env": {
        "GITLAB_URL": "https://git.inteli.edu.br",
        "GITLAB_TOKEN": "glpat-xxxxxxxxxxxxxxxxxxxx"
      }
    }
  }
}
```

### 3. Restart VS Code

The MCP server is now ready to use with Claude or other AI assistants!

## Usage with Different Clients

### Claude Desktop / Claude Code

Add to `~/.config/Claude/claude_desktop_config.json` (macOS) or `%APPDATA%\Claude\claude_desktop_config.json` (Windows):

```json
{
  "mcpServers": {
    "gitlab-inteli": {
      "command": "npx",
      "args": ["@inteli-tools/gitlab-mcp@latest"],
      "env": {
        "GITLAB_URL": "https://git.inteli.edu.br",
        "GITLAB_TOKEN": "glpat-xxxxxxxxxxxxxxxxxxxx"
      }
    }
  }
}
```

### Cursor

Edit `.cursor/mcp.json`:

```json
{
  "mcpServers": {
    "gitlab-inteli": {
      "command": "node",
      "args": ["/absolute/path/to/dist/index.js"],
      "env": {
        "GITLAB_URL": "https://git.inteli.edu.br",
        "GITLAB_TOKEN": "glpat-xxxxxxxxxxxxxxxxxxxx"
      }
    }
  }
}
```

### VS Code (Alternative: Project-Level Config)

Create `.vscode/mcp.json` in your workspace:

```json
{
  "servers": {
    "gitlab-inteli": {
      "type": "stdio",
      "command": "node",
      "args": ["/absolute/path/to/dist/index.js"],
      "env": {
        "GITLAB_URL": "https://git.inteli.edu.br",
        "GITLAB_TOKEN": "glpat-xxxxxxxxxxxxxxxxxxxx"
      }
    }
  }
}
```

## Tool Categories

All GitLab tools use the `gitlab_` prefix.

| Category | Tools | Count |
|----------|-------|-------|
| **Groups** | list_groups, get_group, get_group_members | 3 |
| **Projects** | list_projects, get_project, create_project, fork_project | 4 |
| **Boards** | list_boards, get_board, list_board_lists, list_board_cards | 4 |
| **Issues** | list_issues, create_issue, update_issue, close_issue | 4 |
| **Merge Requests** | list_merge_requests, create_merge_request, merge_merge_request | 3 |
| **Commits** | list_commits, get_commit, get_commit_diff | 3 |
| **Pipelines** | list_pipelines, get_pipeline, get_pipeline_jobs | 3 |
| **Repository** | get_repository_tree, get_file_contents, list_branches | 3 |
| **Search** | search_projects, search_issues, search_code | 3 |
| **Audit** | audit_repository, audit_project, get_repository_stats | 3 |

## Configuration

All configuration is done through environment variables:

| Variable | Default | Description |
|----------|---------|-------------|
| `GITLAB_URL` | `https://git.inteli.edu.br` | GitLab instance URL |
| `GITLAB_TOKEN` | *required* | Personal Access Token (PAT) from GitLab |
| `LOG_LEVEL` | `info` | Logging level: `debug`, `info`, `warn`, `error` |

### Example with Custom Environment

```json
{
  "mcpServers": {
    "gitlab-inteli": {
      "command": "npx",
      "args": ["@inteli-tools/gitlab-mcp@latest"],
      "env": {
        "GITLAB_URL": "https://git.inteli.edu.br",
        "GITLAB_TOKEN": "glpat-xxxxxxxxxxxxxxxxxxxx",
        "LOG_LEVEL": "debug"
      }
    }
  }
}
```

## Development

### Setup

```bash
git clone https://github.com/Inteli-Tools/Gitlab-MCP.git
cd Gitlab-MCP
npm install
```

### Build

```bash
npm run build
```

### Run Locally

```bash
# Using development mode (with tsx)
GITLAB_URL=https://git.inteli.edu.br GITLAB_TOKEN=your_token npm run dev

# Using compiled version
GITLAB_URL=https://git.inteli.edu.br GITLAB_TOKEN=your_token npm start
```

### Scripts

```bash
npm run build          # Compile TypeScript  
npm run dev            # Run with hot-reload (tsx)
npm run start          # Run compiled version
npm run prepublishOnly # Run before npm publish (auto-build)
```

## Publishing

### NPM Registry

1. **Ensure you're logged in:**
   ```bash
   npm login
   ```

2. **Build and publish:**
   ```bash
   npm version patch  # or minor/major
   npm publish
   ```

### Automated Publishing with GitHub Actions

Push to main:
```bash
git add .
git commit -m "feat: your feature"
git push origin main
```

Create a release on GitHub → GitHub Actions automatically publishes to npm! 🚀

## Architecture

```
src/
├── index.ts                 # MCP server entry point
├── gitlab-client.ts         # GitLab API client
└── tools/
    ├── groups.ts            # Group management
    ├── projects.ts          # Project operations
    ├── boards.ts            # Board/list operations
    ├── issues.ts            # Issue management
    ├── commits.ts           # Commit history
    ├── pipelines.ts         # CI/CD pipelines
    ├── repository.ts        # Repository utilities
    ├── search.ts            # Search functionality
    └── audit.ts             # Repository auditing
```

## Authentication

### Creating a GitLab Personal Access Token

1. Navigate to http://git.inteli.edu.br
2. Go to Settings → Access Tokens
3. Create token with scopes:
   - `api` — For full API access
   - `read_repository` — For repository access (recommended for read-only operations)
4. Copy the token and add to your MCP configuration

### Best Practices

- ✅ Use **read-only scopes** when possible
- ✅ Rotate tokens regularly
- ✅ Never commit tokens to git
- ✅ Use environment variables or `.env` files (add to `.gitignore`)

## Troubleshooting

### Authentication Failed

```
ERROR: 401 Unauthorized
```

**Solution:** Verify your token is correct and not expired. Generate a new one.

### Repository Not Found

```
ERROR: 404 Not Found
```

**Solution:** Check that the project exists and you have access to it.

### Connection Timeout

```
ERROR: ECONNREFUSED
```

**Solution:** Ensure GitLab URL is correct and your network allows outbound HTTPS connections.

## Documentation

- [Publishing Guide](PUBLISHING.md) — How to publish new versions
- [GitHub](https://github.com/Inteli-Tools/Gitlab-MCP)

## License

MIT

## Contributing

Contributions are welcome! Please:

1. Fork the repository
2. Create a feature branch (`git checkout -b feature/amazing-feature`)
3. Commit changes (`git commit -m 'feat: add amazing feature'`)
4. Push to branch (`git push origin feature/amazing-feature`)
5. Open a Pull Request

## Support

For issues, questions, or suggestions:

- [GitHub Issues](https://github.com/Inteli-Tools/Gitlab-MCP/issues)

---

Made with ❤️ by [Inteli Tools](https://github.com/Inteli-Tools)