JIRA MCP server for AI agents

The JIRA MCP server provides a Model Context Protocol for interacting with JIRA APIs through Claude Desktop, allowing you to manage JIRA issues, projects, and users directly from your AI assistant.

Installation

Prerequisites

You'll need:

Python installed on your system
A JIRA instance and API credentials

Setup Steps

Clone the 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 and configure the .env file:
```
touch .env
```

Add your JIRA credentials to the .env file:

JIRA_SERVER=https://your-domain.atlassian.net
[email protected]
JIRA_API_TOKEN=your_api_token_here

Start the MCP server:
```
python run.py
```

Getting a JIRA API Token

To authenticate with JIRA:

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

Usage

Searching Issues

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

search_issues(jql="project=PROJECT AND issuetype=Bug AND priority=High")

Parameters:

jql: JIRA Query Language string
max_results: Maximum number of results (default: 10)
fields: Comma-separated list of fields to include (default: "summary,status,assignee,priority,issuetype")

Creating Issues

Create a new JIRA issue:

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

Parameters:

project_key: The project key (e.g., "DEMO")
summary: Issue summary
description: Issue description (optional)
issue_type: Type of issue (default: "Task")
priority: Priority (optional, e.g., "High", "Medium", "Low")
assignee: Username to assign to (optional)

Updating Issues

Update an existing JIRA issue:

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

Parameters:

issue_key: The JIRA issue key (e.g., "PROJ-123")
summary: New summary (optional)
description: New description (optional)
status: New status (optional)
priority: New priority (optional)
assignee: New assignee (optional)
comment: Comment to add (optional)

Other Operations

Deleting Issues

delete_issue(issue_key="PROJECT-123", confirm=True)

Listing Projects

list_projects(limit=5)

Adding Comments

add_comment(issue_key="PROJECT-123", comment="The fix has been deployed to production")

Transitioning Issues

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

Getting Issue Details

get_issue_details(issue_key="PROJECT-123", include_comments=True)

Searching Users

search_users(query="john", max_results=20, include_inactive_users=False)

Troubleshooting

Common Issues

Module Import Error

# 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 includes 'https://'

GDPR Compliance

If you're using a JIRA Cloud instance with 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
Search for users with the query parameter instead of username

How to install this MCP server

For Claude Code

To add this MCP server to Claude Code, run this command in your terminal:

claude mcp add-json "jira" '{"command":"python","args":["run.py"]}'

See the official Claude Code MCP documentation for more details.

For Cursor

There are two ways to add an MCP server to Cursor. The most common way is to add the server globally in the ~/.cursor/mcp.json file so that it is available in all of your projects.

If you only need the server in a single project, you can add it to the project instead by creating or adding it to the .cursor/mcp.json file.

Adding an MCP server to Cursor globally

To add a global MCP server go to Cursor Settings > Tools & Integrations and click "New MCP Server".

When you click that button the ~/.cursor/mcp.json file will be opened and you can add your server like this:

{
    "mcpServers": {
        "jira": {
            "command": "python",
            "args": [
                "run.py"
            ]
        }
    }
}

Adding an MCP server to a project

To add an MCP server to a project you can create a new .cursor/mcp.json file or add it to the existing one. This will look exactly the same as the global MCP server example above.

How to use the MCP server

Once the server is installed, you might need to head back to Settings > MCP and click the refresh button.

The Cursor agent will then be able to see the available tools the added MCP server has available and will call them when it needs to.

You can also explicitly ask the agent to use the tool by mentioning the tool name and describing what the function does.

For Claude Desktop

To add this MCP server to Claude Desktop:

1. Find your configuration file:

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

2. Add this to your configuration file:

{
    "mcpServers": {
        "jira": {
            "command": "python",
            "args": [
                "run.py"
            ]
        }
    }
}

3. Restart Claude Desktop for the changes to take effect