Devparihar5/Jira-MCP-Server

Jira MCP Server

A comprehensive Python-based MCP (Model Context Protocol) server for Atlassian Jira that enables AI assistants like Claude to interact with Jira seamlessly. This enterprise-grade solution provides full-featured Jira integration with robust error handling, multiple deployment modes, and extensive tool coverage.

Features

Core Issue Management

• Get detailed issue information with customizable fields and expansions
• Create new issues with full field support and validation
• Create child issues (subtasks) with automatic parent linking
• Update existing issues with partial field updates and conflict resolution
• Search issues using powerful JQL (Jira Query Language) with result formatting
• List available issue types for any project with metadata
• Transition issues through workflow states with validation

Advanced Issue Operations

• Move issues to sprints (bulk operations up to 50 issues)
• Link issues with relationship types (blocks, duplicates, relates to, etc.)
• Get related issues and their complete relationship graph
• Retrieve issue history and detailed change logs
• Track workflow transitions and state changes

Comments & Time Tracking

• Add comments to issues with rich text formatting
• Retrieve all comments from issues with threading support
• Add worklogs with flexible time tracking and custom start times
• Time format support (3h, 30m, 1h 30m, 2d 4h, etc.)
• Worklog management with automatic time calculations

Sprint & Project Management

• List all sprints for boards or projects with status filtering
• Get active sprint information with issue details
• Get detailed sprint information by ID with metrics
• List project statuses and available transitions
• Get boards with project associations and permissions
• Sprint analytics and progress tracking

Enterprise Features

• Async/await architecture for high-performance operations
• Comprehensive error handling with detailed debugging information
• Stdio mode deployment optimized for MCP clients
• Docker containerization with security best practices
• Environment-based configuration with validation
• Rich response formatting optimized for AI consumption
• Type safety with Pydantic models and validation
• Bulk operations with progress tracking and error recovery

Installation

Prerequisites

• Python 3.11 or higher
• Atlassian account with Jira access
• API token from Atlassian

Option 1: Using pip (Recommended)

# Clone the repository
git clone https://github.com/Devparihar5/Jira-MCP-Server.git
cd Jira-MCP-Server

# Create virtual environment
python -m .venv venv
source .venv/bin/activate  # On Windows: venv\Scripts\activate

# Install dependencies
pip install -r requirements.txt

Option 2: Using Docker

# Build the image
docker build -t jira-mcp-python .

# Run with environment variables
docker run --rm -i \
  -e ATLASSIAN_HOST=https://your-company.atlassian.net \
  -e ATLASSIAN_EMAIL=your-email@company.com \
  -e ATLASSIAN_TOKEN=your-api-token \
  jira-mcp-python

Configuration

Environment Variables

Create a .env file (copy from .env.example):

ATLASSIAN_HOST=https://your-company.atlassian.net
ATLASSIAN_EMAIL=your-email@company.com
ATLASSIAN_TOKEN=your-api-token

Getting Your API Token

1. Go to Atlassian API Tokens
2. Click "Create API token"
3. Give it a name like "Jira MCP Python"
4. Copy the token (you won't see it again!)

Usage

Stdio Mode (Default)

python main.py --env .env

HTTP Server Mode

# Start HTTP server on default port 8000
python main.py --http --env .env

# Start HTTP server on custom port
python main.py --http --port 3000 --env .env

Configuration

Cursor Configuration

For Stdio Mode:

{
  "mcpServers": {
    "jira": {
      "command": "python",
      "args": ["/path/to/python-jira-mcp/main.py", "--env", "/path/to/.env"],
      "cwd": "/path/to/python-jira-mcp"
    }
  }
}

For HTTP Server Mode:

{
  "mcpServers": {
    "jira": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-everything", "http://localhost:8000/sse"]
    }
  }
}

For Docker (Stdio Mode):

{
  "mcpServers": {
    "jira": {
      "command": "docker",
      "args": [
        "run", "--rm", "-i",
        "-e", "ATLASSIAN_HOST=https://your-company.atlassian.net",
        "-e", "ATLASSIAN_EMAIL=your-email@company.com",
        "-e", "ATLASSIAN_TOKEN=your-api-token",
        "jira-mcp-python"
      ]
    }
  }
}

For Docker (HTTP Mode):

{
  "mcpServers": {
    "jira": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-everything", "http://localhost:8000/sse"]
    }
  }
}

Available Tools

The Python implementation provides 19 comprehensive tools for complete Jira integration:

Issue Management Tools

• get_issue - Get detailed issue information with customizable fields
• create_issue - Create a new issue with full field support
• create_child_issue - Create a subtask with automatic parent linking
• update_issue - Update issue fields with conflict resolution
• list_issue_types - List available issue types for projects
• transition_issue - Transition issue through workflow states

Search & Query Tools

• search_issues - Search issues with JQL and advanced filtering

Sprint Management Tools

• list_sprints - List sprints for boards/projects with status filtering
• get_sprint - Get detailed sprint information by ID
• get_active_sprint - Get currently active sprint with metrics
• move_issues_to_sprint - Move multiple issues to sprint (bulk operations)

Project & Status Tools

• list_project_statuses - List available statuses and transitions
• get_boards - Get boards with project associations

Comment & Time Tracking Tools

• add_comment - Add comments with rich text formatting
• get_comments - Get all comments with threading support
• add_worklog - Log time with flexible format support

Relationship & History Tools

• link_issues - Link issues with relationship types
• get_related_issues - Get complete relationship graph
• get_issue_history - Get detailed change history and transitions

Usage Examples

Once configured, you can ask Claude to help with Jira tasks:

Issue Management

• "Create a new bug ticket for the login issue"
• "Show me details for ticket PROJ-123"
• "Move ticket PROJ-456 to In Progress"
• "Add a comment to PROJ-789 saying the fix is ready"

Sprint Management

• "What's in our current sprint?"
• "Move these 3 tickets to the next sprint: PROJ-1, PROJ-2, PROJ-3"
• "Show me all tickets assigned to John in the current sprint"

Reporting & Analysis

• "Show me all bugs created this week"
• "List all tickets that are blocked"
• "What tickets are ready for testing?"

Development

Project Structure

jira-mcp/
├── main.py                           # Entry point with stdio/HTTP modes
├── requirements.txt                  # Dependencies
├── .env.example                     # Environment template
├── Dockerfile                       # Docker containerization
├── services/
│   ├── __init__.py
│   └── jira_client.py              # Async Jira API client
├── tools/                          # Comprehensive MCP tools
│   ├── __init__.py                 # Tool registration
│   ├── comprehensive_jira_tools.py # Main tool definitions
│   ├── tool_handlers.py            # Core issue handlers
│   ├── comment_time_handlers.py    # Comment & worklog handlers
│   ├── relationship_history_handlers.py # Link & history handlers
│   ├── sprint_handlers.py          # Sprint management handlers
│   └── project_handlers.py         # Project & status handlers
└── utils/
    ├── __init__.py
    └── jira_formatter.py           # AI-optimized formatting

Contributing

1. Fork the repository
2. Create a feature branch (git checkout -b feature/amazing-feature)
3. Make your changes
4. Add tests for new functionality
5. Run code quality checks
6. Commit your changes (git commit -m 'feat: add amazing feature')
7. Push to the branch (git push origin feature/amazing-feature)
8. Open a Pull Request

License

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

Acknowledgments

• Atlassian Python API for Jira integration
• MCP Python SDK for MCP protocol support