GitLab MCP Server
A Model Context Protocol (MCP) server for interacting with GitLab repositories, issues, merge requests, and more.
Features
- List and get project details
- Manage issues (list, create)
- Manage merge requests (list, create)
- Access repository files
- List branches and commits
- User information
Installation
- Install the required dependencies:
pip install -r requirements.txt
- Set up your GitLab access token:
export GITLAB_TOKEN="your-gitlab-token"
# Optional: for self-hosted GitLab
export GITLAB_URL="https://gitlab.example.com"
Usage
Option 1: Run as MCP Server
Run the server directly:
python server.py
Option 2: Use with LangGraph Agent (Recommended)
The gitlab_agent.py provides a high-level interface using LangGraph's ReAct agent:
import asyncio
from gitlab_agent import GitLabAgent
async def main():
# Initialize the agent
agent = GitLabAgent()
# Simple invoke
response = await agent.invoke("Show me my GitLab projects")
# Structured output
structured = await agent.invoke_structured(
"Create an issue titled 'Fix bug' in project 12345"
)
print(structured.user_output)
print(structured.action_taken)
print(structured.resource_url)
# Clean up
await agent.aclose()
asyncio.run(main())
Option 3: Interactive Examples
Run the interactive example script:
python example_usage.py
This provides a menu with various examples:
- List projects
- Create issues
- Manage merge requests
- Browse repository files
- Conversational mode
Available Tools
get_project
Get details about a specific GitLab project.
Parameters:
project_id(required): The ID or URL-encoded path of the project
list_issues
List issues in a GitLab project.
Parameters:
project_id(required): The ID or URL-encoded path of the projectstate(optional): Filter by state (opened, closed, all)
create_issue
Create a new issue in a GitLab project.
Parameters:
project_id(required): The ID or URL-encoded path of the projecttitle(required): The title of the issuedescription(optional): The description of the issuelabels(optional): Comma-separated list of label names
list_merge_requests
List merge requests in a GitLab project.
Parameters:
project_id(required): The ID or URL-encoded path of the projectstate(optional): Filter by state (opened, closed, merged, all)
create_merge_request
Create a new merge request in a GitLab project.
Parameters:
project_id(required): The ID or URL-encoded path of the projectsource_branch(required): The source branch nametarget_branch(required): The target branch nametitle(required): The title of the merge requestdescription(optional): The description of the merge request
get_file_content
Get the content of a file from a GitLab repository.
Parameters:
project_id(required): The ID or URL-encoded path of the projectfile_path(required): The path to the file in the repositoryref(optional): The branch, tag, or commit SHA (default: main)
list_branches
List branches in a GitLab project.
Parameters:
project_id(required): The ID or URL-encoded path of the project
list_commits
List commits in a GitLab project.
Parameters:
project_id(required): The ID or URL-encoded path of the projectref_name(optional): The name of a branch, tag, or commit SHA
Resources
gitlab://projects: List of accessible GitLab projectsgitlab://user: Information about the authenticated user
Configuration
Set the following environment variables:
GITLAB_TOKEN(required): Your GitLab personal access tokenGITLAB_URL(optional): GitLab instance URL (default: https://gitlab.com)OPENAI_API_KEY(required for agent): Your OpenAI API key
Getting a GitLab Token
- Go to your GitLab instance (gitlab.com or your self-hosted instance)
- Navigate to Settings > Access Tokens
- Create a personal access token with the following scopes:
api- Access the APIread_repository- Read repository contentwrite_repository- Write to repository (if needed)
Agent Architecture
The GitLab Agent uses:
- LangGraph: For the ReAct agent framework
- LangChain: For LLM integration (OpenAI)
- MCP Client: To connect to the GitLab MCP server
- Structured Outputs: Using Pydantic models for reliable response parsing
Agent Features
- 🔄 Conversational: Maintains context across multiple interactions
- 🎯 Tool Selection: Automatically selects the right GitLab tools
- 📊 Structured Outputs: Returns typed, validated responses
- 🔍 Logging: Detailed logging of all operations
- 💾 Checkpointing: Saves conversation state
Example Agent Interactions
# List projects
await agent.invoke("What GitLab projects do I have access to?")
# Get project info
await agent.invoke("Tell me about project 12345")
# Create an issue
await agent.invoke_structured(
"Create a bug report in project myuser/myrepo titled 'Login fails'"
)
# List merge requests
await agent.invoke("Show me open merge requests in project 12345")
# Get file content
await agent.invoke("Show me the README.md file from project 12345")
Files
server.py- Main MCP server implementationgitlab_agent.py- LangGraph agent wrapperexample_usage.py- Interactive examplesrequirements.txt- MCP server dependenciesrequirements-agent.txt- Agent dependencies.env.example- Environment variable template
License
MIT