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:

pip install -r requirements.txt

2. 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 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

# 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