Quickstart

Prerequisites

Before installing Jira MCP, you need to set up the Jira CLI that the MCP server uses to execute commands.

Install jira-cli

Follow the installation instructions for your operating system from the jira-cli repository.

Get Jira API credentials

Depending on your Jira implementation (Cloud or Self-Hosted), you will need to use a different authentication type.Add these to your .bashrc, .zshrc, or other shell configuration file:

# https://id.atlassian.com/manage-profile/security/api-tokens
export JIRA_API_KEY=""

# `bearer` for token,
# `basic` for Jira account API token
# `password` for Jira account password
export JIRA_AUTH_TYPE="basic"

Make sure to source the file after adding the credentials:

source ~/.bashrc

See alternative credential methods for other ways to configure authentication.

Initialize jira-cli

jira init

This will prompt you for your Jira URL and credentials.

Test jira-cli

jira issue list

This should return a list of issues in Jira.

Install the MCP server

Choose your preferred installation method:

Download binary (Recommended)
Development setup with uv
Install globally with pipx

Download the latest release for your operating system from the Releases page.

Operating System	Binary
Linux	`jira-mcp-linux`
Windows	`jira-mcp-windows.exe`
macOS (Apple Silicon)	`jira-mcp-macos-apple-silicon-arm64`
macOS (Intel)	`jira-mcp-macos-x64`

Linux

# Download the binary
curl -L -o jira-mcp https://github.com/xcollantes/jira-mcp/releases/latest/download/jira-mcp-linux

# Make it executable
chmod +x jira-mcp

# Move to a directory in your PATH (optional)
sudo mv jira-mcp /usr/local/bin/

Add to your LLM client configuration:

{
  "mcpServers": {
    "jira": {
      "command": "/usr/local/bin/jira-mcp"
    }
  }
}

Replace /usr/local/bin/jira-mcp with the path to the binary on your machine if you moved it to a different location.

macOS

# For Apple Silicon (M1/M2/M3)
curl -L -o jira-mcp https://github.com/xcollantes/jira-mcp/releases/latest/download/jira-mcp-macos-apple-silicon-arm64

# For Intel Macs
curl -L -o jira-mcp https://github.com/xcollantes/jira-mcp/releases/latest/download/jira-mcp-macos-x64

# Make it executable
chmod +x jira-mcp

# Move to a directory in your PATH (optional)
sudo mv jira-mcp /usr/local/bin/

macOS may block the binary on first run. If you see a security warning, go to System Settings > Privacy & Security and click Allow Anyway, or run:

xattr -d com.apple.quarantine /usr/local/bin/jira-mcp

Add to your LLM client configuration:

{
  "mcpServers": {
    "jira": {
      "command": "/usr/local/bin/jira-mcp"
    }
  }
}

Replace /usr/local/bin/jira-mcp with the path to the binary on your machine if you moved it to a different location.

Windows

Download jira-mcp-windows.exe from the Releases page.
Move the executable to a convenient location (e.g., C:\Program Files\jira-mcp\).

Add to your LLM client configuration:

{
  "mcpServers": {
    "jira": {
      "command": "C:\\Program Files\\jira-mcp\\jira-mcp-windows.exe"
    }
  }
}

Replace C:\\Program Files\\jira-mcp\\jira-mcp-windows.exe with the path to the binary on your machine if you moved it to a different location.

Clone the repository:

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

Add MCP server to your LLM client configuration:

{
  "mcpServers": {
    "jira": {
      "command": "uv",
      "args": [
        "--directory",
        "/ABSOLUTE/PATH/TO/REPO/ROOT",
        "run",
        "python",
        "-m",
        "src.main"
      ]
    }
  }
}

This tells your LLM client that there is a tool that can be called by running uv --directory /ABSOLUTE/PATH/TO/REPO run python -m src.main.

Install UV if you haven’t already: UV installation guide

# Install pipx if you haven't already
brew install pipx
pipx ensurepath

# Clone and install the MCP server
git clone https://github.com/xcollantes/jira-mcp.git
cd jira-mcp
pipx install -e .

Next steps

Configure Cursor

Set up Jira MCP in Cursor IDE.

Configure Claude Code

Set up Jira MCP with Claude Code CLI.

Configure Windsurf

Set up Jira MCP in Windsurf.

Development

Contribute to Jira MCP development.

Getting started

AI tool setup

Prerequisites

Install the MCP server

Next steps

Configure Cursor

Configure Claude Code

Configure Windsurf

Development

Getting started

AI tool setup

​Prerequisites

​Install the MCP server

​Next steps

Configure Cursor

Configure Claude Code

Configure Windsurf

Development

Prerequisites

Install the MCP server

Next steps