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

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 : 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

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

Create Issues

Manage Issues

Project Information

Available Tools 🛠️

Configuration Options ⚙️

Environment Variables

JQL Examples

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

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:

Testing API Connection

You can test your Jira connection independently:

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.