README.md
GitLab MCP Server
MCP (Model Context Protocol) server for AI-assisted code review with GitLab on-premise instances.
Features
Merge Request Tools
- List, get, create merge requests
- Get MR changes, commits, pipelines
- Get and add discussions/comments
- Approve, unapprove, merge MRs
Repository Tools
- List projects
- Browse repository tree
- Get file content and blame
- Search code
- List branches and commits
Security Model
Uses OAuth with intersection-based access control:
- User authenticates via GitLab OAuth
- AI access limited to repos both user AND service account can access
- All API calls made with service account token for audit trail
Prerequisites
- Python 3.11+
- GitLab instance with OAuth application configured
- SSL certificate for HTTPS
Setup
1. GitLab OAuth Application
Create in GitLab Admin > Applications:
- Redirect URI:
https://<server-host>:/oauth/callback - Scopes:
read_user,read_api,read_repository,api(for write operations) - Confidential: Yes
2. Secrets File
Create a JSON file with credentials:
{
"oauth_client_id": "<gitlab-oauth-app-id>",
"oauth_client_secret": "<gitlab-oauth-app-secret>",
"service_token": "<service-account-personal-access-token>"
}
3. Environment Variables
| Variable | Required | Description |
|---|---|---|
GITLAB_URL |
yes | GitLab instance URL |
GITLAB_SECRETS_PATH |
yes | Path to secrets JSON file |
MCP_SERVER_BIND_URL |
yes | Bind URL with protocol and port (e.g., https://0.0.0.0:8443 or http://0.0.0.0:8080) |
MCP_SERVER_ADVERTISED_URL |
yes | Client-facing URL (e.g., https://mcp.example.com:8443) |
MCP_SSL_CERT_PATH |
when bind uses https | Path to SSL certificate |
MCP_SSL_KEY_PATH |
when bind uses https | Path to SSL private key |
SSL_CERT_FILE |
no | CA certificate for GitLab (self-signed certs) |
4. Install
pip install .
Running
gitlab-mcp
Development
pip install -e ".[dev]"
pytest
Tools 2
merge_request_toolsTools for listing, creating, and managing merge requests including discussions and approvals.repository_toolsTools for browsing repository trees, searching code, and listing branches or commits.Environment Variables
GITLAB_URLrequiredGitLab instance URLGITLAB_SECRETS_PATHrequiredPath to secrets JSON fileMCP_SERVER_BIND_URLrequiredBind URL with protocol and portMCP_SERVER_ADVERTISED_URLrequiredClient-facing URLMCP_SSL_CERT_PATHPath to SSL certificateMCP_SSL_KEY_PATHPath to SSL private keySSL_CERT_FILECA certificate for GitLabTry it
→List all open merge requests assigned to me in the main project.
→Get the changes for merge request #123 and summarize the impact on the codebase.
→Search the repository for all instances of the authentication module.
→Add a comment to merge request #123 suggesting a refactor for the error handling logic.
→List the recent commits on the develop branch for the current project.