Jira MCP Server 🎫

A Model Context Protocol (MCP) server that integrates with Jira Cloud to provide comprehensive issue management, project tracking, and team collaboration capabilities directly through Claude and other MCP clients.

Features ✨

Issue Management

• Search Issues: Advanced JQL-based searching with simple filters
• Get Issue Details: Comprehensive issue information with comments
• Create Issues: Create Stories, Bugs, Tasks, and other issue types
• Update Issues: Change status, assignee, priority, and summary
• Add Comments: Add comments to existing issues
• My Issues: Quick access to your assigned tickets

Project Management

• List Projects: View all accessible projects
• Project Details: Get comprehensive project information
• Issue Types: See available issue types per project

Smart Features

• Flexible User Assignment: Use 'me', 'myself', or actual usernames/emails
• Status Transitions: Automatically handle Jira workflow transitions
• Rich Text Support: Handles Atlassian Document Format (ADF)
• Error Handling: Comprehensive error messages and validation

Quick Start 🚀

1. Prerequisites

• Python 3.10 or higher
• Claude Desktop - Download and install from claude.ai/download
• Access to a Jira Cloud instance
• Jira API token (we'll generate this below)

2. Installation

# Clone this repository
git clone https://github.com/jondoesflow/MCP_Server_JIra.git
cd MCP_Server_JIra

# Install uv (Python package manager) if not already installed
curl -LsSf https://astral.sh/uv/install.sh | sh
source $HOME/.local/bin/env

# Set up virtual environment and install dependencies
$HOME/.local/bin/uv venv
$HOME/.local/bin/uv add "mcp[cli]" httpx python-dotenv

3. Jira API Setup

1. Generate an API Token:

   • Go to Atlassian Account Security
   • Click "Create API token"
   • Give it a name (e.g., "MCP Server")
   • Copy the generated token (save it somewhere safe!)

2. Create Environment Configuration:

   # Copy the example environment file
   cp .env.example .env
   

3. Edit the .env file: Open the .env file in your text editor and fill in your actual values:

   # Your Jira Cloud instance URL (without trailing slash)
   JIRA_BASE_URL=https://yourcompany.atlassian.net
   
   # Your Jira account email
   JIRA_EMAIL=your.email@company.com
   
   # Your Jira API token (paste the token you generated above)
   JIRA_API_TOKEN=your_actual_api_token_here
   

   Important: Replace the placeholder values with your actual Jira details!

4. Test Your Connection

# Test your Jira connection before proceeding
$HOME/.local/bin/uv run test_connection.py

This should show:

• ✅ Successful login to your Jira instance
• ✅ List of accessible projects
• ✅ Ability to search for issues

If any tests fail, double-check your .env file values.

5. Configure Claude Desktop

1. Create the Claude Desktop configuration file:

   macOS: ~/Library/Application Support/Claude/claude_desktop_config.json Windows: %APPDATA%\Claude\claude_desktop_config.json

2. Add this configuration (replace /ABSOLUTE/PATH/TO/ with your actual path):

   {
     "mcpServers": {
       "jira": {
         "command": "/Users/yourusername/.local/bin/uv",
         "args": [
           "--directory",
           "/ABSOLUTE/PATH/TO/MCP_Server_JIra",
           "run",
           "jira_server.py"
         ]
       }
     }
   }
   

   To find your absolute path, run this in the project directory:

   pwd
   

3. Example configuration (update the username and path):

   {
     "mcpServers": {
       "jira": {
         "command": "/Users/jonathanrussell/.local/bin/uv",
         "args": [
           "--directory",
           "/Users/jonathanrussell/Documents/VIbe/MCP/MCP_Server_JIra",
           "run",
           "jira_server.py"
         ]
       }
     }
   }
   

6. Restart Claude Desktop

Important: Completely quit and restart Claude Desktop for the changes to take effect. You should then see MCP tools available in the interface.

Usage Examples 💡

Search for Issues

"Show me all high priority bugs in the MOBILE project"
"Find issues assigned to me that are in progress"
"Search for issues with 'login' in the title"

Create Issues

"Create a bug report for the login timeout issue in project WEB"
"Create a story for implementing dark mode, assign it to me"
"Create a task to update documentation with high priority"

Manage Issues

"Move ticket WEB-123 to In Progress"
"Assign ticket MOBILE-456 to john.doe@company.com"
"Add a comment to WEB-123 saying 'Fixed in latest build'"

Project Information

"List all available projects"
"Show me details about the MOBILE project"
"What are my current assigned issues?"

Available Tools 🛠️

Tool	Description
search_issues	Search issues with JQL or simple filters
get_issue	Get detailed information about a specific issue
get_my_issues	Get issues assigned to you
create_issue	Create new issues (Stories, Bugs, Tasks)
update_issue	Update issue status, assignee, priority, summary
add_comment	Add comments to issues
list_projects	List all accessible projects
get_project_info	Get detailed project information

Configuration Options ⚙️

Environment Variables

Variable	Description	Required
JIRA_BASE_URL	Your Jira Cloud URL (e.g., https://company.atlassian.net)	Yes
JIRA_EMAIL	Your Jira account email	Yes
JIRA_API_TOKEN	Your Jira API token	Yes

JQL Examples

The server supports full JQL (Jira Query Language) for advanced searching:

project = "WEB" AND assignee = currentUser() AND status != Done
priority in (High, Highest) AND created >= -7d
issuetype = Bug AND status = "In Progress"
text ~ "login" AND project in (WEB, MOBILE)

Troubleshooting 🔧

Common Issues

1. "Missing required environment variables"

   • Ensure your .env file exists and contains all required variables
   • Check that variable names match exactly (case-sensitive)

2. "Jira API error: 401"

   • Verify your email and API token are correct
   • Ensure the API token hasn't expired
   • Check that your Jira URL is correct (no trailing slash)

3. "User not found" when assigning

   • Use exact email addresses or usernames
   • Try using 'me' to assign to yourself
   • Verify the user has access to the project

4. "Status not available" when updating

   • Check available transitions with the error message
   • Jira workflows restrict which status changes are allowed
   • Use exact status names (case-sensitive)

Debug Mode

To enable detailed logging, modify the logging level in jira_server.py:

logging.basicConfig(level=logging.DEBUG)

Testing API Connection

You can test your Jira connection independently:

# Test API connection
curl -u "your.email@company.com:your_api_token" \
  -H "Accept: application/json" \
  "https://yourcompany.atlassian.net/rest/api/3/myself"

Security Notes 🔒

• API Tokens: Never commit your .env file to version control
• Permissions: The server respects your Jira permissions - you can only access what you normally can
• Rate Limiting: The server includes basic rate limiting respect for Jira's API limits
• HTTPS Only: Always use HTTPS Jira URLs for secure communication

Contributing 🤝

This MCP server is designed to be extensible. To add new features:

1. Add new tool functions using the @mcp.tool() decorator
2. Follow the existing error handling patterns
3. Update this README with new functionality
4. Test thoroughly with your Jira instance

License 📄

This project is open source. Feel free to modify and distribute according to your needs.

---

Need Help? Check the MCP Documentation or Jira REST API Documentation.