Jira-GitLab MCP Server

A Python-based Model Context Protocol (MCP) server that integrates Jira and GitLab, enabling AI agents to seamlessly manage issues and branches across both platforms.

Features

• Jira Integration: Fetch issues, add comments, and manage project data
• GitLab Integration: Create branches, manage projects, and handle repository operations
• AI-Powered Analysis: Real OpenAI integration for intelligent issue analysis and code generation
• Automated Workflow: Complete SRE workflow from issue detection to fix deployment
• Code Validation: AST-based validation with security pattern detection
• Secure Configuration: Support for environment variables and encrypted credentials
• Robust Error Handling: Comprehensive error management with retry mechanisms
• Async Support: Full asynchronous operation for better performance
• MCP Compliance: Fully compatible with the Model Context Protocol specification

Quick Start

Prerequisites

• Python 3.8+
• Jira account with API access
• GitLab account with Personal Access Token

Installation

1. Clone the repository:

git clone <repository-url>
cd mcp-jira-gitlab

2. Install dependencies:

pip install -r requirements.txt

3. Configure credentials (choose one method):

Option A: Environment Variables (Recommended)

export JIRA_BASE_URL="https://yourcompany.atlassian.net"
export JIRA_EMAIL="your-email@example.com"
export JIRA_API_TOKEN="your-jira-api-token"
export GITLAB_BASE_URL="https://gitlab.com"
export GITLAB_ACCESS_TOKEN="your-gitlab-personal-access-token"

Option B: Configuration File

cp config.json.sample config.json
# Edit config.json with your credentials

4. Run the MCP server:

python mcp_server.py

Configuration

Environment Variables

Variable	Description	Required
JIRA_BASE_URL	Your Jira instance URL	Yes
JIRA_EMAIL	Your Jira account email	Yes
JIRA_API_TOKEN	Jira API token	Yes
GITLAB_BASE_URL	GitLab instance URL	No (defaults to gitlab.com)
GITLAB_ACCESS_TOKEN	GitLab Personal Access Token	Yes

Generating API Tokens

Jira API Token:

1. Go to Atlassian Account Settings
2. Click "Create API token"
3. Copy the generated token

GitLab Personal Access Token:

1. Go to GitLab → Settings → Access Tokens
2. Create token with api, read_repository, and write_repository scopes
3. Copy the generated token

MCP Tools

create_branch_for_issue

Creates a GitLab branch for a Jira issue and links them.

Parameters:

• issue_key (string): Jira issue key (e.g., "PROJ-123")
• project_id (integer): GitLab project ID
• base_branch (string, optional): Base branch (default: "main")

Branch Naming Convention: feature/{issue_key}-fix

Example:

{
  "issue_key": "PROJ-123",
  "project_id": 42,
  "base_branch": "main"
}

get_jira_issues

Fetch Jira issues using JQL query.

Parameters:

• jql (string, optional): JQL query string
• max_results (integer, optional): Maximum results (default: 50)

Example:

{
  "jql": "project = DEMO AND status = 'To Do'",
  "max_results": 25
}

comment_on_issue

Add a comment to a Jira issue.

Parameters:

• issue_key (string): Jira issue key
• comment (string): Comment text

Example:

{
  "issue_key": "PROJ-123",
  "comment": "Branch created and ready for development"
}

get_issues_by_tags

Fetch Jira issues by project and tags (labels).

Parameters:

• project_key (string): Jira project key (e.g., "PROJ", "DEMO")
• tags (array): List of tags/labels to filter by (1-10 tags)
• max_results (integer, optional): Maximum results (default: 50, max: 100)

Example:

{
  "project_key": "PROJ",
  "tags": ["AI-Fix", "AutoFix"],
  "max_results": 25
}

Use Cases:

• Find bugs tagged for AI-assisted fixing: ["AI-Fix", "AutoFix"]
• Locate security issues: ["security", "vulnerability"]
• Filter performance problems: ["performance", "optimization"]
• Identify technical debt: ["tech-debt", "refactor"]

analyze_and_fix_issue

Use AI to analyze a Jira issue and generate code fixes.

Parameters:

• issue_key (string): Jira issue key to analyze
• model (string, optional): AI model to use (default: "gpt-4-turbo")
• validation_level (string, optional): Code validation strictness ("basic" or "strict")
• include_context (boolean, optional): Include repository context (default: true)

Example:

{
  "issue_key": "PROJ-123",
  "model": "gpt-4-turbo",
  "validation_level": "basic"
}

commit_ai_fix

Commit AI-generated fixes to GitLab branch with validation.

Parameters:

• project_id (integer): GitLab project ID
• branch_name (string): Branch name to commit to
• files (array): Files to commit with content and actions
• commit_message (string): Commit message

Example:

{
  "project_id": 42,
  "branch_name": "ai-fix/PROJ-123",
  "files": [
    {
      "path": "src/main.py",
      "content": "# Fixed code here",
      "action": "update"
    }
  ],
  "commit_message": "AI-generated fix for PROJ-123"
}

create_merge_request

Create a GitLab merge request.

Parameters:

• project_id (integer): GitLab project ID
• source_branch (string): Source branch name
• target_branch (string, optional): Target branch (default: "main")
• title (string, optional): MR title
• description (string, optional): MR description
• draft (boolean, optional): Create as draft (default: true)

Example:

{
  "project_id": 42,
  "source_branch": "ai-fix/PROJ-123",
  "title": "AI Fix: Bug in authentication",
  "draft": true
}

update_issue_status

Update Jira issue status and add comments.

Parameters:

• issue_key (string): Jira issue key
• status (string): New status (e.g., "In Review", "Done")
• comment (string, optional): Comment to add with status change

Example:

{
  "issue_key": "PROJ-123",
  "status": "In Review",
  "comment": "AI-generated fix created and ready for review"
}

sre_ai_workflow

Complete SRE AI workflow: fetch tagged issues, create fixes, and update status.

Parameters:

• project_key (string): Jira project key
• gitlab_project_id (integer): GitLab project ID
• tags (array, optional): Tags to filter by (default: ["AI-Fix", "AutoFix"])
• max_issues (integer, optional): Maximum issues to process (default: 5)
• auto_merge (boolean, optional): Auto-merge approved fixes (default: false)

Example:

{
  "project_key": "PROJ",
  "gitlab_project_id": 42,
  "tags": ["AI-Fix", "security"],
  "max_issues": 3
}

Workflow Steps:

1. Fetch issues with specified tags
2. Analyze each issue with AI
3. Generate and validate code fixes
4. Create branches and commit changes
5. Create draft merge requests
6. Update Jira issue status to "In Review"

MCP Resources

jira://issues

Access to Jira issues in the configured project.

gitlab://projects

Access to GitLab projects and branches.

Development

Running Tests

# Install test dependencies
pip install pytest pytest-asyncio pytest-mock pytest-cov

# Run all tests
pytest

# Run with coverage
pytest --cov=. --cov-report=html

# Run specific test file
pytest tests/test_mcp_server.py

Project Structure

mcp-jira-gitlab/
├── mcp_server.py           # Main MCP server implementation
├── server.py               # Legacy FastAPI server (deprecated)
├── config.json             # Configuration file (optional)
├── requirements.txt        # Python dependencies
├── README.md              # This file
├── connectors/
│   ├── jira_client.py     # Jira API client
│   ├── gitlab_client.py   # GitLab API client
│   └── requirements.txt   # Connector dependencies
├── utils/
│   ├── error_handler.py   # Error handling utilities
│   └── config.py          # Configuration management
└── tests/
    ├── test_mcp_server.py # MCP server tests
    └── test_clients.py    # Client tests

Error Handling

The server implements comprehensive error handling:

• Retry Mechanisms: Automatic retry with exponential backoff
• Authentication Errors: Clear messages for credential issues
• API Rate Limiting: Handles rate limits gracefully
• Network Issues: Robust handling of connection problems
• Validation: Input validation with helpful error messages

Logging

The server uses Python's logging module with configurable levels:

import logging
logging.basicConfig(level=logging.INFO)

Usage Examples

Basic Workflow

1. Fetch Jira Issues:

# Using MCP tool
{
  "tool": "get_jira_issues",
  "arguments": {
    "jql": "project = MYPROJ AND status = 'To Do'"
  }
}

2. Create Branch for Issue:

# Using MCP tool
{
  "tool": "create_branch_for_issue", 
  "arguments": {
    "issue_key": "MYPROJ-123",
    "project_id": 42
  }
}

3. Add Progress Comment:

# Using MCP tool
{
  "tool": "comment_on_issue",
  "arguments": {
    "issue_key": "MYPROJ-123",
    "comment": "Development started in branch feature/MYPROJ-123-fix"
  }
}

Integration with AI Agents

This MCP server is designed to work with AI agents and LLMs. Example integration:

# Example AI agent workflow
async def handle_new_issue(issue_key, project_id):
    # 1. Get issue details
    issues = await mcp_client.call_tool("get_jira_issues", {
        "jql": f"key = {issue_key}"
    })
    
    # 2. Create branch
    result = await mcp_client.call_tool("create_branch_for_issue", {
        "issue_key": issue_key,
        "project_id": project_id
    })
    
    # 3. Add status comment
    await mcp_client.call_tool("comment_on_issue", {
        "issue_key": issue_key,
        "comment": "Automated branch creation completed"
    })

Security Considerations

• Environment Variables: Use environment variables for production
• Token Rotation: Regularly rotate API tokens
• Network Security: Use HTTPS for all API communications
• Access Control: Limit token permissions to minimum required
• Logging: Avoid logging sensitive information

Troubleshooting

Common Issues

Authentication Errors:

• Verify API tokens are correct and not expired
• Check that email matches Jira account
• Ensure GitLab token has required permissions

Connection Issues:

• Verify base URLs are correct
• Check network connectivity
• Confirm firewall settings allow HTTPS traffic

Permission Errors:

• Ensure Jira user has project access
• Verify GitLab token has repository permissions
• Check project visibility settings

Debug Mode

Enable debug logging:

import logging
logging.basicConfig(level=logging.DEBUG)

Contributing

1. Fork the repository
2. Create a feature branch
3. Make your changes
4. Add tests for new functionality
5. Run the test suite
6. Submit a pull request

License

This project is licensed under the MIT License - see the LICENSE file for details.

Support

For issues and questions:

1. Check the troubleshooting section
2. Review existing GitHub issues
3. Create a new issue with detailed information

Changelog

v1.0.0

• Initial MCP server implementation
• Jira and GitLab integration
• Comprehensive error handling
• Full test coverage
• Documentation and examples