README.md•5.69 kB
# 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
1. Install the required dependencies:
```bash
pip install -r requirements.txt
```
2. Set up your GitLab access token:
```bash
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:
```bash
python server.py
```
### Option 2: Use with LangGraph Agent (Recommended)
The `gitlab_agent.py` provides a high-level interface using LangGraph's ReAct agent:
```python
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:
```bash
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 project
- `state` (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 project
- `title` (required): The title of the issue
- `description` (optional): The description of the issue
- `labels` (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 project
- `state` (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 project
- `source_branch` (required): The source branch name
- `target_branch` (required): The target branch name
- `title` (required): The title of the merge request
- `description` (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 project
- `file_path` (required): The path to the file in the repository
- `ref` (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 project
- `ref_name` (optional): The name of a branch, tag, or commit SHA
## Resources
- `gitlab://projects`: List of accessible GitLab projects
- `gitlab://user`: Information about the authenticated user
## Configuration
Set the following environment variables:
- `GITLAB_TOKEN` (required): Your GitLab personal access token
- `GITLAB_URL` (optional): GitLab instance URL (default: https://gitlab.com)
- `OPENAI_API_KEY` (required for agent): Your OpenAI API key
## Getting a GitLab Token
1. Go to your GitLab instance (gitlab.com or your self-hosted instance)
2. Navigate to Settings > Access Tokens
3. Create a personal access token with the following scopes:
- `api` - Access the API
- `read_repository` - Read repository content
- `write_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
```python
# 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 implementation
- `gitlab_agent.py` - LangGraph agent wrapper
- `example_usage.py` - Interactive examples
- `requirements.txt` - MCP server dependencies
- `requirements-agent.txt` - Agent dependencies
- `.env.example` - Environment variable template
## License
MIT