This repository contains a Model Context Protocol (MCP) server that connects your AI assistants (like Cursor, Gemini, Claude Desktop) directly to any self-hosted Jira Server or Jira Cloud instance. It enables your AI to seamlessly manage tasks, create issues, and query your project management workflow without leaving the chat interface.
## Features Supported
-**Fetch Assigned Tasks:** Get all open tasks currently assigned to you.
-**View Issue Details:** Retrieve full information about a specific issue (description, status, priority, reporter).
-**List Projects:** View exactly what projects exist and their keys.
-**Active Project Context:** Set an active project for your session so you don't have to keep repeating the project key when creating issues.
-**Create Issues:** Generate new Jira tasks directly from the chat interface.
-**Create Bulk Issues:** Effortlessly create dozen of issues, bugs, and tasks simultaneously in a single command.
-**Create Advanced Issues:** Specify labels, components, assignee, due date, original estimates, priority, and environment when creating issues, just like the web interface.
-**Create Issue with Subtasks:** Automatically generate a parent Story or Task and link multiple subtasks to it in a single command.
-**Assign Issues:** Automatically assign existing or newly created issues to yourself.
-**Update Status:** Transition issues through your Jira workflow (e.g., to "Ready for QA").
-**Search Jira (JQL):** Run advanced queries against you Jira using standard JQL syntax.
-**Issue Comments:** Read the conversation history on a ticket or post a new comment.
-**Log Work:** Record time spent on a task directly from your AI interface.
---
## ⚙️ How to Setup
### Prerequisites
Make sure you have Python installed on your system.
### Installation
#### Mac / Linux
1. Clone this repository or download the source code:
```bash
git clone <REPOSITORY_URL>
cd <REPOSITORY_DIRECTORY>
```
2. Set up a virtual environment and install dependencies:
```bash
python3 -m venv venv
source venv/bin/activate
pip install mcp jira
```
#### Windows
1. Clone this repository or download the source code:
```cmd
git clone <REPOSITORY_URL>
cd <REPOSITORY_DIRECTORY>
```
2. Set up a virtual environment and install dependencies:
```cmd
python -m venv venv
venv\Scripts\activate
pip install mcp jira
```
### 1. Claude Desktop Configuration
Edit your `claude_desktop_config.json` file to include the server. Replace the placeholder paths with your actual absolute paths, and fill in your Jira credentials.
6. Click Save and make sure it has the green status circle indicating it's connected.
*(Note: In Cursor, environment variables are typically inherited from your shell. If you find Cursor isn't passing environment variables correctly, you can also inject them by prefixing the command with `env JIRA_SERVER=... JIRA_USERNAME=... JIRA_PASSWORD=... <command>` on Mac/Linux, or fallback to setting them safely if you know how).*
---
## 🤖 Example Prompts
Once the MCP server is running, the AI has direct access to your Jira. You don't need to specify the URL or API details anymore. Just talk to the AI naturally!
Here are examples of what you can ask:
### 📋 Checking Your Work
> *"What are my open assigned tasks in Jira?"*
>
> *"Can you show me the details for issue PQCI-875?"*
>
> *"Summarize the description of PQCI-877 for me."*
>
> *"What is my active project?"*
>
> *"Set my active project to PQCI."*
### ➕ Creating Tasks
You can specify absolutely any Issue Type that is valid on your Jira server when creating an issue. E.g.:
> *"Create a new task in the PQCAL Mobile project (PCM) to 'Fix the broken login button on iOS'. The description should say that it crashes on the staging environment."*
>
> *"I just realized we need a new button on the dashboard. Please create a Jira ticket for this." (Requires an active project to be set!)*
#### Creating Issues with Subtasks
> *"Create a story titled 'Allow Admin to Change Trader of an Investor' with the following subtasks:*
> *- Front-end: Design*
> *- Back-end: Develop"*
>
> *"Create a Task titled 'Migrate database' with subtasks:*
> *- Backup*
> *- Run migration*
> *- Verify data"*
#### Advanced Task Creation
> *"Create a major priority bug for the 'login' component, assigned to 'shahidul', with label 'frontend', environment 'iOS', due '2026-10-31', and an original estimate of '3d 4h'. Support this with description X."*
#### Bulk Issue Creation
> *"I have a list of 5 tasks I need created at once in PQCI:*
> *- Update logo*
> *- Fix header bug (issue_type=Bug)*
> *- Write documentation*
> *- Audit dependencies*
> *- Update readme"*
### 👤 Modifying Assignments
> *"Assign the ticket PCM-228 to me."*
>
> *"Create a new task for 'Update API Documentation' in PCM, and assign it to me right away."*
### 🔄 Updating Statuses
> *"I just finished working on PCM-131. Please transition it to 'Ready for QA'."*
>
> *"Move PQCI-873 to 'Start Progress'."*
>
> *"What transitions are currently available for my task PCM-228?"*
### 💬 Communication & Time Logging
> *"Can you fetch the comments on issue PCM-123?"*
>
> *"Add a comment to PQCI-875 saying: 'I've addressed the feedback in my latest PR.'"*
>
> *"Log 2h 30m of work on PCM-229."*
### 🔍 Advanced Search (JQL)
> *"Find all issues in the PCM project containing the word 'login' that are unassigned."*
>
> *"List all high-priority bugs reported this week."*
>
> *"What issues are currently in 'Ready for QA' status for PQCI?"*
