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
-
Clone this repository:
git clone https://github.com/yourusername/mcp-jira.git cd mcp-jira -
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 -
Install dependencies:
pip install -r requirements.txt -
Create a
.envfile in the project root:touch .env -
Add your JIRA credentials to the
.envfile:JIRA_SERVER=https://your-domain.atlassian.net JIRA_EMAIL=your.email@example.com JIRA_API_TOKEN=your_api_token_here -
Test the installation:
# Run all tests python -m pytest # Run a specific test file python -m pytest tests/test_search_issues.py -
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:
- Log in to your Atlassian account
- Go to Account Settings > Security > Create and manage API tokens
- Click "Create API token"
- Give it a name (e.g., "Claude Desktop Integration")
- 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):
- User searches will only match against display names and email addresses
- Username-based searches are not supported
- Results may be limited based on user permissions
- The tool automatically handles GDPR requirements, but you may need to adjust your search patterns
Troubleshooting
Common issues and solutions:
-
ModuleNotFoundError: No module named 'src'
# Run with PYTHONPATH set PYTHONPATH=/path/to/mcp-jira python run.py -
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://'
-
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
- Log in to your Atlassian account
- Go to Account Settings > Security > Create and manage API tokens
- Click "Create API token"
- Give it a name (e.g., "Claude Desktop Integration")
- 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
queryparameter instead ofusername. 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:
- Clone the repository
- Set up a virtual environment:
python -m venv venv && source venv/bin/activate - Install dependencies:
pip install -r requirements.txt - Run tests:
python -m pytest - Make your changes
- Test with Claude Desktop