jira-mcp-tools 0.2.3

Model Context Protocol server for Jira integration

MCP Server for JIRA

A Model Context Protocol (MCP) server that provides seamless integration with Jira. This server enables AI assistants to retrieve issue information, comments, and attachments from any Jira instance.

Features

• 🎫 Issue Management: Get, create, update, and transition issues
• 🔍 Advanced Search: JQL-based issue search with custom fields
• 📊 Epic & Sprint Tracking: Monitor progress, story points, and completion
• 🔗 Issue Relationships: View and manage issue links
• 💬 Comments: Add and retrieve issue comments
• 📎 Attachments: Download issue attachments
• 📜 History: Track all changes to issues
• 🚀 Release Management: View project versions and releases
• 👥 Assignment: Assign/unassign issues to users
• 🔒 Secure Authentication: Uses Jira API tokens

Installation

Using uvx (Recommended)

uvx jira-mcp-tools

Using pip

pip3 install jira-mcp-tools

Prerequisites

• Python 3.10 or higher
• Jira API token (How to create)
• UV package manager (Installation guide)

Configuration

Environment Variables

The server requires three environment variables:

• JIRA_URL: Your Jira instance URL
• JIRA_EMAIL: Your Jira account email
• JIRA_TOKEN: Your Jira API token

MCP Client Configuration

Add to your MCP client configuration (e.g., Claude Desktop, Bob):

{
  "mcpServers": {
    "jira": {
      "command": "uvx",
      "args": ["jira-mcp-tools"],
      "env": {
        "JIRA_URL": "https://jsw.ibm.com/",
        "JIRA_EMAIL": "[e-mail]",
        "JIRA_TOKEN": "your-api-token"
      }
    }
  }
}

Available Tools

Issue Information

get_jira_ticket_info

Get detailed information about a Jira issue including description and comments.

Parameters:

• issue_key (string): Issue key (e.g., "PROJ-123")

Example: get_jira_ticket_info("PROJ-123")

get_jira_ticket_attachments

Download attachments from a Jira issue.

Parameters:

• issue_key (string): Issue key

Example: get_jira_ticket_attachments("PROJ-456")

get_issue_history

Get complete change history of an issue including status transitions and field updates.

Parameters:

• issue_key (string): Issue key

Example: get_issue_history("PROJ-123")

get_issue_links

Get all linked issues (blocks, relates to, etc.).

Parameters:

• issue_key (string): Issue key

Example: get_issue_links("PROJ-123")

Search & Discovery

search_issues

Search for issues using JQL (Jira Query Language).

Parameters:

• jql (string): JQL query (e.g., 'project = PROJ AND status = "In Progress"')
• max_results (int, optional): Maximum results (default: 50)
• fields (string, optional): Comma-separated field list

Examples:

search_issues('project = MYPROJ')
search_issues('assignee = currentUser() AND status != Done')
search_issues('updated >= -7d ORDER BY updated DESC')

Epic & Sprint Management

get_epic_details

Get epic information including child issues, progress metrics, and story points.

Parameters:

• epic_key (string): Epic issue key

Example: get_epic_details("PROJ-123")

get_sprint_info

Get sprint information for a board.

Parameters:

• board_id (int): Jira board ID
• sprint_id (int, optional): Specific sprint ID (omit for all sprints)

Examples:

get_sprint_info(42)  # All sprints for board 42
get_sprint_info(42, 123)  # Specific sprint

Project Management

get_project_releases

Get all releases/versions for a project with associated issues.

Parameters:

• project_key (string): Project key (e.g., "PROJ")

Example: get_project_releases("PROJ")

Issue Modification

create_issue

Create a new Jira issue.

Parameters:

• project_key (string): Project key
• summary (string): Issue title
• description (string): Issue description
• issue_type (string, optional): Issue type (default: "Task")

Example: create_issue("PROJ", "Fix bug", "Description here", "Bug")

update_issue

Update fields of an existing issue.

Parameters:

• issue_key (string): Issue key
• fields (dict): Fields to update

Examples:

update_issue("PROJ-123", {"summary": "New title"})
update_issue("PROJ-123", {"priority": {"name": "High"}})
update_issue("PROJ-123", {"labels": ["bug", "urgent"]})

transition_issue

Move an issue to a new status.

Parameters:

• issue_key (string): Issue key
• transition_name (string): Transition name (e.g., "In Progress", "Done")

Example: transition_issue("PROJ-123", "In Progress")

assign_issue

Assign an issue to a user.

Parameters:

• issue_key (string): Issue key
• assignee (string): Username/email (use "none" to unassign)

Example: assign_issue("PROJ-123", "[e-mail]")

add_comment

Add a comment to an issue.

Parameters:

• issue_key (string): Issue key
• comment_text (string): Comment text

Example: add_comment("PROJ-123", "This is a comment")

Development

Local Development Setup

1. Clone the repository

   git clone <repository-url>
   cd mcp-jira
   

2. Install dependencies

   uv sync
   

3. Configure environment

   cp env.template .env
   # Edit .env with your Jira credentials:
   # JIRA_URL=https://your-instance.atlassian.net/
   # JIRA_EMAIL=[e-mail]
   # JIRA_TOKEN=your-api-token
   

4. Run the server

   uv run mcp_jira/server.py
   

Testing with Bob

1. Add to Bob's MCP settings (~/.bob/mcp_settings.json or via Bob UI):

   {
     "mcpServers": {
       "jira": {
         "command": "uv",
         "args": ["--directory", "/path/to/mcp-jira", "run", "mcp_jira/server.py"],
         "env": {
           "JIRA_URL": "https://your-instance.atlassian.net/",
           "JIRA_EMAIL": "[e-mail]",
           "JIRA_TOKEN": "your-api-token"
         }
       }
     }
   }
   

2. Restart Bob to load the MCP server

3. Switch to Advanced mode in Bob to access MCP tools

4. Test the connection:

   • Ask Bob: "Search for issues in project PROJ"
   • Or: "Get details for issue PROJ-123"

Running Tests

# Run tests
uv run pytest

# Run with coverage
uv run pytest --cov

Use Cases

• AI-Assisted Development: Let AI assistants fetch and analyze Jira issues
• Automated Workflows: Integrate Jira data into automated processes
• Context-Aware Coding: Provide issue context to AI coding assistants
• Documentation: Auto-generate documentation from Jira issues

Roadmap

• Support for creating and updating issues
• Advanced search capabilities
• Support for Jira workflows and transitions
• Enhanced attachment handling (PDFs, images)
• Bulk operations support

Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

License

MIT License - see LICENSE file for details.

Support

• Issues: GitHub Issues
• Documentation: Full Documentation

Acknowledgments

Built with:

• FastMCP - Fast MCP server framework
• jira-python - Python Jira library
• Model Context Protocol - MCP specification