Skip to content

Commit 4ebf8b4

Browse files
author
Nisha Saini
committed
Merge branch 'main' into use-makefile
2 parents 0d4e476 + 08bc9c2 commit 4ebf8b4

File tree

2 files changed

+209
-1
lines changed

2 files changed

+209
-1
lines changed

‎README.md

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

‎gitlab_mcp_server.py

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -827,4 +827,4 @@ def main():
827827
mcp.run()
828828

829829
if __name__ == "__main__":
830-
main()
830+
main()

0 commit comments

Comments
 (0)