@inteli-tools/gitlab-mcp

A production-ready MCP 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.

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

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

Or use directly without global install:

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)"):

{
  "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):

{
  "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:

{
  "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:

{
  "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

{
  "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

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

Build

npm run build

Run Locally

# 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

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:

   npm login

2. Build and publish:

   npm version patch  # or minor/major
   npm publish

Automated Publishing with GitHub Actions

Push to main:

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 — How to publish new versions
• GitHub

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

Made with ❤️ by Inteli Tools