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
- Clone the repository:
git clone <repository-url>
cd mcp-jira-gitlab
- Install dependencies:
pip install -r requirements.txt
- 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
- 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:
- Go to Atlassian Account Settings
- Click "Create API token"
- Copy the generated token
GitLab Personal Access Token:
- Go to GitLab → Settings → Access Tokens
- Create token with
api,read_repository, andwrite_repositoryscopes - 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 IDbase_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 stringmax_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 keycomment(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 analyzemodel(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 IDbranch_name(string): Branch name to commit tofiles(array): Files to commit with content and actionscommit_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 IDsource_branch(string): Source branch nametarget_branch(string, optional): Target branch (default: "main")title(string, optional): MR titledescription(string, optional): MR descriptiondraft(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 keystatus(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 keygitlab_project_id(integer): GitLab project IDtags(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:
- Fetch issues with specified tags
- Analyze each issue with AI
- Generate and validate code fixes
- Create branches and commit changes
- Create draft merge requests
- 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
- Fetch Jira Issues:
# Using MCP tool
{
"tool": "get_jira_issues",
"arguments": {
"jql": "project = MYPROJ AND status = 'To Do'"
}
}
- Create Branch for Issue:
# Using MCP tool
{
"tool": "create_branch_for_issue",
"arguments": {
"issue_key": "MYPROJ-123",
"project_id": 42
}
}
- 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
- Fork the repository
- Create a feature branch
- Make your changes
- Add tests for new functionality
- Run the test suite
- Submit a pull request
License
This project is licensed under the MIT License - see the LICENSE file for details.
Support
For issues and questions:
- Check the troubleshooting section
- Review existing GitHub issues
- 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