hackerdogs/gitlab-mcp repository overview

⁠

⁠GitLab MCP Server

MCP server wrapper for GitLab⁠ — manage repositories, issues, merge requests, and CI/CD pipelines via the GitLab API using the @zereight/mcp-gitlab npm package. See zereight/mcp-gitlab⁠ for full documentation.

⁠What is GitLab MCP?

@zereight/mcp-gitlab is an MCP server that wraps the GitLab REST API, giving AI assistants the ability to list and create issues, review and merge MRs, inspect pipeline status, browse repository file trees, and read file contents — all authenticated with a GitLab personal access token. It supports both gitlab.com and self-hosted GitLab instances via the GITLAB_URL environment variable.

Personal access token required — create one at GitLab Settings → Access Tokens with api scope and set GITLAB_PERSONAL_ACCESS_TOKEN.

⁠Tools Reference

⁠Example Prompts

Here are example prompts you can use with Claude (or any MCP client) when this tool is connected:

• "List all open merge requests in my-group/my-project and summarize the changes."
• "Show the status of the latest CI/CD pipeline for my-group/my-project on the main branch."
• "Create a new issue in my-group/my-project titled 'Fix authentication timeout' with a description of the problem."
• "Read the contents of src/main.py from the main branch of my-group/my-project."
• "List all open issues labeled 'critical' in my-group/my-project."
• "Show me the failed jobs in pipeline #12345 for my-group/my-project and explain the errors."

⁠Deploy

⁠Docker Compose (recommended)

docker-compose up -d

⁠Docker Run (stdio mode)

docker run -i --rm \
  -e GITLAB_PERSONAL_ACCESS_TOKEN \
  hackerdogs/gitlab-mcp:latest

⁠Docker Run (HTTP streamable mode)

docker run -d -p 8642:8642 \
  -e MCP_TRANSPORT=streamable-http \
  -e MCP_PORT=8642 \
  -e GITLAB_PERSONAL_ACCESS_TOKEN \
  hackerdogs/gitlab-mcp:latest

⁠MCP Client Configuration

⁠Stdio mode (default)

Add to your Claude Desktop or Cursor MCP config:

{
  "mcpServers": {
    "gitlab-mcp": {
      "command": "docker",
      "args": [
        "run",
        "-i",
        "--rm",
        "-e",
        "MCP_TRANSPORT",
        "-e",
        "GITLAB_PERSONAL_ACCESS_TOKEN",
        "hackerdogs/gitlab-mcp:latest"
      ],
      "env": {
        "MCP_TRANSPORT": "stdio",
        "GITLAB_PERSONAL_ACCESS_TOKEN": ""
      }
    }
  }
}

⁠HTTP mode (streamable-http)

First, start the server using Docker Compose or docker run with HTTP mode (see Deploy⁠ above), then point your MCP client at the running server:

{
  "mcpServers": {
    "gitlab-mcp": {
      "url": "http://localhost:8642/mcp"
    }
  }
}

⁠Environment Variables

⁠Installing in Hackerdogs

The fastest way to get started is through Hackerdogs⁠:

1. Log in to your Hackerdogs account.
2. Go to the Tools Catalog.
3. Search for the tool by name.
4. Expand the tool card and click Install — you're ready to go.

1. Vendor API key required? Add your key in the config environment variable field before clicking Install. Your key will be encrypted at rest.
2. Enable / Disable the tool anytime from the Enabled Tools page.
3. Need to update a key or parameter? Go to My Tools → toggle Show Decrypted Values → edit → Save.

⁠Build

docker build -t hackerdogs/gitlab-mcp:latest .

⁠Testing

⁠Automated tests

./test.sh

⁠Test directly with Docker

1. Start the server in HTTP mode:

docker run -d --rm --name gitlab-mcp-test -p 8642:8642 \
  -e MCP_TRANSPORT=streamable-http \
  -e GITLAB_PERSONAL_ACCESS_TOKEN \
  hackerdogs/gitlab-mcp:latest

2. Initialize the MCP session:

SESSION_ID=$(curl -s -D - -X POST http://localhost:8642/mcp \
  -H "Content-Type: application/json" \
  -H "Accept: application/json, text/event-stream" \
  -d '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2024-11-05","capabilities":{},"clientInfo":{"name":"test","version":"0.1"}}}' \
  2>&1 | grep -i mcp-session-id | awk '{print $2}' | tr -d '\r\n')

curl -s -X POST http://localhost:8642/mcp \
  -H "Content-Type: application/json" \
  -H "Accept: application/json, text/event-stream" \
  -H "mcp-session-id: $SESSION_ID" \
  -d '{"jsonrpc":"2.0","method":"notifications/initialized"}'

3. List available tools:

curl -s -X POST http://localhost:8642/mcp \
  -H "Content-Type: application/json" \
  -H "Accept: application/json, text/event-stream" \
  -H "mcp-session-id: $SESSION_ID" \
  -d '{"jsonrpc":"2.0","id":2,"method":"tools/list","params":{}}'

4. Clean up:

docker stop gitlab-mcp-test