GitHub release (latest by date) GitHub GitHub stars

Complete project skeleton for connecting VS Code to JIRA using Model Context Protocol (MCP). Get your team querying JIRA with natural language in minutes, not hours!

• 🚀 One-command setup - Complete project scaffolding in seconds
• 🔒 Security-first - No credentials in git, template-based configuration
• 📚 Comprehensive docs - Setup guides, examples, and troubleshooting
• 🎯 Team ready - Perfect for organizations and development teams
• 🌍 Cross-platform - Works on macOS, Linux, and Windows
• ⚡ Natural language queries - "Show me high-priority bugs in project X"

• VS Code installed
• Docker Desktop running
• JIRA Server/Data Center access (not Atlassian Cloud)
• JIRA Personal Access Token
• MCP-compatible VS Code extension

# Clone this repository
git clone <your-repo-url>
cd mcp-jira-integration
# Make scripts executable
chmod +x *.sh
# Run complete setup
./setup-mcp-jira.sh MyJiraProject
# Verify installation
cd MyJiraProject
./verify-setup.sh
# Configure your credentials
./configure.sh

# Basic setup without extras
./simple-setup.sh MyJiraProject

1. Generate JIRA Personal Access Token

   • Go to your JIRA Server instance
   • Navigate to User Profile → Personal Access Tokens
   • Create new token with read permissions
   • ⚠️ IMPORTANT: Save the token securely

2. Configure Environment Variables

   # Edit .env file
   JIRA_URL=https://your-jira-server.com
   JIRA_PERSONAL_TOKEN=your_token_here
   JIRA_SSL_VERIFY=false

3. Setup VS Code MCP Configuration

   • File will be created at .vscode/mcp.json
   • Update with your JIRA credentials

"List all available JIRA projects"
"What issues are in ECAPP project for release 25.28?"
"Give me details of issue ECAPP-10745"

"Generate a markdown summary of all issues in release 25.28 for ECAPP project"
"How many issues does each developer have assigned in ECAPP project?"
"Search issues with JQL: project = ECAPP AND fixVersion = '25.28'"

# Clone repository
git clone https://github.com/r-pedraza/mcp-jira-integration.git
cd mcp-jira-integration
# Run setup (takes ~30 seconds)
./setup-mcp-jira.sh MyJiraProject
# 🚀 MCP-JIRA Integration Setup
# ================================
# Project name: MyJiraProject
# 📁 Creating project structure...
# ✅ Directory structure created
# 📦 Creating requirements.txt...
# 🐍 Setting up Python module...
# 🔧 Creating configuration templates...
# 🛠️ Creating utility scripts...
# 🔒 Creating .gitignore...
# 📚 Creating documentation...
# ✅ All files created successfully
# Configure your credentials
cd MyJiraProject
./configure.sh
# 🔧 MCP-JIRA Configuration Setup
# ================================
# ✅ .env file created from template
# ✅ mcp.json file created from template
# ⚠️ Please edit .env and .vscode/mcp.json with your JIRA credentials
# Edit .env and .vscode/mcp.json with your actual JIRA details
# Then verify everything works
./verify-setup.sh
# 🔍 MCP-JIRA Setup Verification
# ===============================
# ✅ Docker is installed
# ✅ .env file exists
# ✅ .vscode/mcp.json exists
# 🎉 Verification completed!
# Open in VS Code and start querying!
code .

The setup script generates a complete project structure:

MyJiraProject/
├── 📄 README.md # Project documentation
├── 📦 requirements.txt # Python dependencies 
├── 🔧 .env.template/.env # Environment configuration
├── 🔒 .gitignore # Git ignore rules (protects credentials)
├── ⚙️ configure.sh # Configuration helper script
├── ✅ verify-setup.sh # Setup verification script
├── 🐍 mcp_jira/ # Python module
│ ├── __init__.py
│ └── __main__.py # Local configuration checker
├── 🎨 .vscode/
│ └── mcp.json # VS Code MCP configuration
└── 📚 docs/ # Documentation
 └── SETUP_GUIDE.md # Detailed setup instructions

• ✅ No sensitive data in repository - Only templates with placeholder values
• ✅ Credential protection - Real tokens and URLs never committed to git
• ✅ SSL flexibility - Support for self-signed certificates in corporate environments
• ✅ Project filtering - Limit access to specific JIRA projects for performance
• ✅ Template system - Safe configuration management

• Model Context Protocol
• MCP-Atlassian Plugin
• JIRA REST API Documentation

• Verify token validity
• Check token permissions
• For JIRA Server: use Personal Access Token (not Cloud API Token)

"JIRA_SSL_VERIFY": "false"

• Install Docker Desktop
• Verify Docker is in PATH
• Restart VS Code after Docker installation

We welcome contributions! Here's how you can help:

• 🐛 Report bugs by opening an issue
• 💡 Suggest features for better JIRA integration
• 📖 Improve documentation with examples and guides
• 🔧 Submit PRs for bug fixes and enhancements
• ⭐ Star the repository to show your support

# Fork and clone your fork
git clone https://github.com/YOUR-USERNAME/mcp-jira-integration.git
cd mcp-jira-integration
# Test your changes
./setup-mcp-jira.sh TestProject
cd TestProject
./verify-setup.sh

• 📖 Documentation: Check our Setup Guide
• 🐛 Issues: Report bugs or request features
• 💬 Discussions: Join the community discussions
• 📧 Contact: Open an issue for support questions

This project is built on top of excellent open-source tools:

• 🤖 Model Context Protocol - AI assistant integration framework
• 🔌 MCP-Atlassian Plugin - JIRA connectivity for MCP
• 🐳 Docker - Containerized deployment
• 🎨 VS Code - The best code editor

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

If this project helped you, please consider giving it a star! ⭐

Star History Chart

Ready! You can now query JIRA information directly from VS Code using natural language. 🚀

Created on July 22, 2025