JIRA MCP Tools

A Model Context Protocol (MCP) for interacting with JIRA APIs through Claude Desktop.

Features

• Search JIRA issues using JQL (JIRA Query Language)
• List JIRA projects for the authenticated user
• Create, update, and delete JIRA issues
• Add comments and transition issues between statuses
• Search for users (with GDPR compliance support)

Installation

1. Clone this repository:

   git clone https://github.com/yourusername/mcp-jira.git
   cd mcp-jira
   

2. Create and activate a virtual environment:

   # On macOS/Linux
   python -m venv venv
   source venv/bin/activate
   
   # On Windows
   python -m venv venv
   .\venv\Scripts\activate
   

3. Install dependencies:

   pip install -r requirements.txt
   

4. Create a .env file in the project root:

   touch .env
   

5. Add your JIRA credentials to the .env file:

   JIRA_SERVER=https://your-domain.atlassian.net
   JIRA_EMAIL=your.email@example.com
   JIRA_API_TOKEN=your_api_token_here
   

6. Test the installation:

   # Run all tests
   python -m pytest
   
   # Run a specific test file
   python -m pytest tests/test_search_issues.py
   

7. Start the MCP server:

   python run.py
   

Environment Setup

JIRA API Token

You'll need a JIRA API token to authenticate with your JIRA instance:

1. Log in to your Atlassian account
2. Go to Account Settings > Security > Create and manage API tokens
3. Click "Create API token"
4. Give it a name (e.g., "Claude Desktop Integration")
5. Click "Create" and save the generated token securely

GDPR Compliance

If you're using a JIRA Cloud instance (which is likely in GDPR strict mode):

1. User searches will only match against display names and email addresses
2. Username-based searches are not supported
3. Results may be limited based on user permissions
4. The tool automatically handles GDPR requirements, but you may need to adjust your search patterns

Troubleshooting

Common issues and solutions:

1. ModuleNotFoundError: No module named 'src'

   # Run with PYTHONPATH set
   PYTHONPATH=/path/to/mcp-jira python run.py
   

2. JIRA API Authentication Error

   • Verify your API token is correct
   • Check that your email matches your Atlassian account
   • Ensure your JIRA instance URL is correct and includes 'https://'

3. GDPR-related Errors

   • If you see "username parameter not supported" errors, your instance is in GDPR mode
   • Use display names or email addresses for searching instead of usernames
   • The tool will automatically adjust the API calls for GDPR compliance

Getting a JIRA API Token

1. Log in to your Atlassian account
2. Go to Account Settings > Security > Create and manage API tokens
3. Click "Create API token"
4. Give it a name (e.g., "Claude Desktop Integration")
5. Click "Create" and save the generated token securely

Tools

Search Issues

Search for JIRA issues using JQL (JIRA Query Language).

Parameters:

• jql: JIRA Query Language string (e.g., "project=DEMO AND status=Open")
• max_results: Maximum number of results to return (default: 10)
• fields: Comma-separated list of fields to include in the results (default: "summary,status,assignee,priority,issuetype")

Create Issue

Create a new JIRA issue in a specified project.

Parameters:

• project_key: The key of the project to create the issue in (e.g., "DEMO")
• summary: Issue summary
• description: Issue description (optional)
• issue_type: Type of issue (default: "Task", can be "Bug", "Story", etc.)
• priority: Priority of the issue (optional, e.g., "High", "Medium", "Low")
• assignee: Username to assign the issue to (optional)

Update Issue

Update an existing JIRA issue with new values.

Parameters:

• issue_key: The JIRA issue key (e.g., "PROJ-123")
• summary: New summary for the issue (optional)
• description: New description for the issue (optional)
• status: New status for the issue (optional, e.g., "In Progress", "Done")
• priority: New priority for the issue (optional, e.g., "High", "Medium", "Low")
• assignee: New assignee for the issue (optional)
• comment: Comment to add to the issue (optional)

Delete Issue

Delete a JIRA issue (requires explicit confirmation).

Parameters:

• issue_key: The JIRA issue key (e.g., "PROJ-123")
• confirm: Confirmation flag to prevent accidental deletion, must be set to True

List Projects

Lists JIRA projects for the authenticated user.

Parameters:

• limit: Maximum number of projects to return (default: 10)

Add Comment

Add a comment to an existing JIRA issue.

Parameters:

• issue_key: The JIRA issue key (e.g., "PROJ-123")
• comment: The comment text to add to the issue

Transition Issue

Transition a JIRA issue to a new status.

Parameters:

• issue_key: The JIRA issue key (e.g., "PROJ-123")
• status: The target status to transition the issue to (e.g., "In Progress", "Done")
• comment: Optional comment to add with the transition

Get Issue Details

Get detailed information about a JIRA issue.

Parameters:

• issue_key: The JIRA issue key (e.g., "PROJ-123")
• include_comments: Whether to include issue comments in the response (default: False)

Search Users

Search for JIRA users by name, email, or username. This tool helps you find users when you need to assign issues or add watchers.

Important Note: For JIRA Cloud instances with GDPR strict mode enabled (which is the default for newer instances), user search must use the query parameter instead of username. The tool automatically handles this, but you may need to adjust your search patterns accordingly.

Parameters:

• query (str): The search string to match against user display names and email addresses
  • For GDPR-compliant instances, this searches display names and email addresses
  • The search is case-insensitive and matches partial strings
  • Example: "john" will match "John Doe" and "johnny@example.com"
• max_results (int, optional): Maximum number of users to return (default: 10)
• include_active_users (bool, optional): Include active users in search results (default: True)
• include_inactive_users (bool, optional): Include inactive users in search results (default: False)

Example usage:

# Search for users with "john" in their display name or email
search_users(query="john")

# Search for up to 20 users, including inactive ones
search_users(
    query="smith",
    max_results=20,
    include_inactive_users=True
)

GDPR Compliance Notes:

• In GDPR strict mode, user search is more restrictive to protect user privacy
• The search matches against user display names and email addresses only
• Exact username matching is not supported
• The search is always case-insensitive
• Partial matches are supported (e.g., "jo" will match "John")
• Results may be limited based on the user's permissions and privacy settings

Example Usage

Search for bugs in the PROJECT with high priority:
search_issues(jql="project=PROJECT AND issuetype=Bug AND priority=High")

Create a new bug in the PROJECT:
create_issue(project_key="PROJECT", summary="Login button not working", description="Users cannot log in using the login button on the homepage", issue_type="Bug", priority="High")

Update an existing issue:
update_issue(issue_key="PROJECT-123", summary="Updated: Login button fixed", status="In Progress", comment="Fixed the CSS styling issue")

Delete an issue:
delete_issue(issue_key="PROJECT-123", confirm=True)

List the first 5 projects:
list_projects(limit=5)

Add a comment to an issue:
add_comment(issue_key="PROJECT-123", comment="The fix has been deployed to production")

Transition an issue:
transition_issue(issue_key="PROJECT-123", status="In Progress", comment="Starting work on this issue")

Get issue details:
get_issue_details(issue_key="PROJECT-123", include_comments=True)

Development

For developers who want to modify or extend this MCP:

1. Clone the repository
2. Set up a virtual environment: python -m venv venv && source venv/bin/activate
3. Install dependencies: pip install -r requirements.txt
4. Run tests: python -m pytest
5. Make your changes
6. Test with Claude Desktop