Skip to content

Commit 23b2174

Browse files
beingnishasbeingnishas
authored
gitlab-mcp-server with read only access tools
1 parent a252a76 commit 23b2174

File tree

6 files changed

+962
-61
lines changed

6 files changed

+962
-61
lines changed

‎Containerfile

Lines changed: 13 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -1,10 +1,20 @@
11
FROM registry.redhat.io/ubi9/python-311
22

3+
# Set working directory
34
WORKDIR /app
45

5-
COPY requirements.txt ./
6+
# Copy requirements first for better caching
7+
COPY requirements.txt .
8+
9+
# Install Python dependencies
610
RUN pip install --no-cache-dir -r requirements.txt
711

8-
COPY mcp_server.py ./
12+
# Copy server code
13+
COPY gitlab_mcp_server.py .
14+
15+
# Set environment variables
16+
ENV MCP_TRANSPORT=stdio
17+
ENV PYTHONPATH=/app
918

10-
CMD ["python", "mcp_server.py"]
19+
# Run the MCP server
20+
CMD ["python", "gitlab_mcp_server.py"]

‎README.md

Lines changed: 24 additions & 14 deletions
Original file line numberDiff line numberDiff line change
@@ -1,18 +1,34 @@
1-
# mcp-server template
1+
# gitlab-mcp-server
22

3-
MCP (ModelContextProvider) server template
3+
Gitlab MCP (ModelContextProvider) server
44

55
---
66

7+
## Running locally in a MCP client like cursor
8+
9+
To run this MCP server from cursor. Go to cursor settings -> Tools & integrations -> Add MCP server
10+
11+
```json
12+
{
13+
"mcpServers": {
14+
"gitlab-mcp-local": {
15+
"command": "python",
16+
"args": ["gitlab_mcp_server.py"],
17+
"trust": true
18+
}
19+
}
20+
}
21+
```
22+
723
## Building locally
824

925
To build the container image locally using Podman, run:
1026

1127
```sh
12-
podman build -t mcp-server-template:latest .
28+
podman build -t gitlab-mcp-server:latest -f Containerfile .
1329
```
1430

15-
This will create a local image named `mcp-server-template:latest` that you can use to run the server.
31+
This will create a local image named `gitlab-mcp-server:latest` that you can use to run the server.
1632

1733
## Running with Podman or Docker
1834

@@ -21,22 +37,16 @@ Example configuration for running with Podman:
2137
```json
2238
{
2339
"mcpServers": {
24-
"mcp-server": {
40+
"gitlab-mcp-server": {
2541
"command": "podman",
2642
"args": [
2743
"run",
2844
"-i",
2945
"--rm",
30-
"-e", "API_BASE_URL",
31-
"-e", "API_KEY",
32-
"-e", "MCP_TRANSPORT",
33-
"localhost/mcp-server-template:latest"
46+
"--env", "MCP_GITLAB_URL",
47+
"--env", "MCP_GITLAB_TOKEN",
48+
"localhost/gitlab-mcp-server:latest"
3449
],
35-
"env": {
36-
"API_BASE_URL": "https://api.example.com",
37-
"API_KEY": "REDACTED",
38-
"MCP_TRANSPORT": "stdio"
39-
}
4050
}
4151
}
4252
}

‎Usage_steps.md

Lines changed: 178 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,178 @@
1+
# GitLab MCP Server - Usage Guide
2+
3+
## Overview
4+
This GitLab MCP Server provides tools using **read-only** access. It has comprehensive functions for exploring and monitoring GitLab projects.
5+
6+
## Available Functions
7+
8+
### 🔍 Search & Discovery
9+
- `search_repositories` - Find projects by name, description, or path
10+
- `list_issues` - List issues in a project
11+
- `list_merge_requests` - List merge requests in a project
12+
- `list_pipelines` - List pipelines in a project
13+
- `list_jobs` - List jobs in a specific pipeline
14+
15+
### 📊 Monitoring & Analysis
16+
- `check_latest_failed_jobs` - Find recent failed jobs across pipelines
17+
- `list_latest_commits` - View recent commits in projects
18+
19+
## Correct Query Patterns
20+
21+
### For Project Discovery
22+
✅ **Correct Prompts:**
23+
- "Search for projects containing 'systemd'"
24+
- "Find repositories with 'kernel' in the name"
25+
- "List my owned projects"
26+
- "Show all public repositories"
27+
28+
❌ **Avoid:**
29+
- Single word searches without context
30+
- Vague terms like "find stuff"
31+
32+
### For Failed Jobs Analysis
33+
✅ **Correct Prompts:**
34+
- "List the failed jobs in mcp-servers project"
35+
- "Show recent failed jobs for project ID 123"
36+
- "Find failed pipeline jobs in the last few runs"
37+
38+
❌ **Avoid:**
39+
- Just saying "failed jobs" without specifying project
40+
41+
### For Project Monitoring
42+
✅ **Correct Prompts:**
43+
- "Show recent pipelines for project 456"
44+
- "List open issues in my-project"
45+
- "Show merge requests waiting for review in project XYZ"
46+
- "Get latest commits from all my projects"
47+
48+
## Step by step example:
49+
50+
When you ask: **"List the failed jobs in mcp-servers project"**
51+
52+
The MCP follows:
53+
1. 🔍 **Search for project:** Use `search_repositories` with search_term="mcp-servers"
54+
2. 📋 **Get project ID:** Extract the project ID from search results
55+
3. ❌ **List failed jobs:** Use `check_latest_failed_jobs` with that project ID
56+
4. 📊 **Display results:** Show the recent failed jobs with details
57+
58+
## Function Details
59+
60+
### search_repositories
61+
```json
62+
{
63+
"search_term": "mcp-servers", // Optional: project name/description
64+
"visibility": "all", // public, private, internal, all
65+
"owned": false, // true for only owned repos
66+
"limit": 10 // max results
67+
}
68+
```
69+
70+
### check_latest_failed_jobs
71+
```json
72+
{
73+
"project_id": "123", // Required: GitLab project ID
74+
"limit": 5 // Optional: max failed jobs to return
75+
}
76+
```
77+
78+
### list_issues
79+
```json
80+
{
81+
"project_id": "123", // Required: GitLab project ID
82+
"state": "opened", // opened, closed, all
83+
"limit": 20 // max results
84+
}
85+
```
86+
87+
### list_pipelines
88+
```json
89+
{
90+
"project_id": "123", // Required: GitLab project ID
91+
"status": "all", // running, pending, success, failed, all
92+
"limit": 20 // max results
93+
}
94+
```
95+
96+
## Security Features
97+
98+
- ✅ **Rate limiting:** Max 100 API calls per hour (configurable)
99+
- ✅ **Action restrictions:** Only "read" actions allowed by default
100+
- ✅ **Repository access control:** Configurable repo allowlist
101+
- ✅ **Error handling:** Graceful failures with helpful messages
102+
103+
## Environment Configuration
104+
105+
```bash
106+
# Required
107+
export MCP_GITLAB_TOKEN="your-gitlab-token"
108+
109+
# Optional
110+
export GITLAB_URL="https://gitlab.example.com"
111+
export MCP_MAX_API_CALLS="100"
112+
export MCP_ALLOWED_ACTIONS="read"
113+
export MCP_ALLOWED_REPOS="project1,project2" # Empty = all allowed
114+
```
115+
116+
## Example Workflows
117+
118+
### 1. Investigate Failed Jobs
119+
```
120+
Human: "List failed jobs in mcp-tests project"
121+
→ MCP searches for "mcp-tests" project
122+
→ MCP gets project ID from search results
123+
→ MCP lists recent failed jobs with details
124+
```
125+
126+
### 2. Project Health Check
127+
```
128+
Human: "Show pipeline status for my-app project"
129+
→ MCP searches for "my-app" project
130+
→ MCP lists recent pipelines with status
131+
→ Human can drill down into specific pipelines
132+
```
133+
134+
### 3. Issue Tracking
135+
```
136+
Human: "What open issues are there in frontend-app?"
137+
→ MCP searches for "frontend-app" project
138+
→ MCP lists open issues with assignees and dates
139+
```
140+
141+
## Best Practices
142+
143+
### 🎯 Be Specific
144+
- Include project names in queries
145+
- Specify what information you want (issues, MRs, pipelines, etc.)
146+
- Use descriptive terms rather than abbreviations
147+
148+
### 🔄 Multi-Step Queries
149+
The MCP can now handle complex queries that require multiple steps:
150+
1. Search for project by name
151+
2. Get specific information about that project
152+
3. Drill down into details as needed
153+
154+
### 📊 Use Filters
155+
Most functions support filtering:
156+
- **States:** opened, closed, merged, failed, success
157+
- **Limits:** Control result size for performance
158+
- **Visibility:** Focus on relevant repositories
159+
160+
## Troubleshooting
161+
162+
### Common Issues
163+
164+
**🚫 "Project not found"**
165+
- Try broader search terms
166+
- Check if you have access to the project
167+
- Verify project name spelling
168+
169+
**🚫 "Rate limit exceeded"**
170+
- Wait an hour for limit reset
171+
- Increase `MCP_MAX_API_CALLS` if needed
172+
173+
**🚫 "Access denied"**
174+
- Check `MCP_ALLOWED_REPOS` configuration
175+
- Verify your GitLab token has proper permissions
176+
- Ensure you're a project member
177+
178+
This read-only approach provides safer, more focused GitLab integration for monitoring and analysis workflows.

0 commit comments

Comments
 (0)