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

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!)

Create Environment Configuration:

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

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

Create the Claude Desktop configuration file:

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

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

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

"Missing required environment variables"
- Ensure your .env file exists and contains all required variables
- Check that variable names match exactly (case-sensitive)
"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)
"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
"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:

Add new tool functions using the @mcp.tool() decorator
Follow the existing error handling patterns
Update this README with new functionality
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.