MCP Jira Cloud

A Model Context Protocol (MCP) server that enables AI assistants like GitHub Copilot and Claude to interact with your Jira Cloud instance. Search issues, manage tickets, log work, and more — all through natural language conversation.

🎯 Why Use This Package?

Supported AI Assistants

✨ Features

🔐 Authentication

• Basic Auth (API Token)
• OAuth 2.0 with auto-refresh
• Secure credential storage via Keytar

📋 Issue Management

• Full CRUD operations
• Workflow transitions
• Search with JQL

🏃 Agile/Scrum

• Sprint management (create, start, complete)
• Board views (Scrum & Kanban)
• Backlog & ranking

🔗 Relationships

• Issue linking (blocks, relates, duplicates)
• Watchers & voting
• Epic management

⏱️ Time Tracking

• Log work on issues
• View work logs
• Query worklogs by user & date range
• Flexible time formats

🗄️ Filters & Metadata

• Create/manage saved filters
• Field metadata access
• Component & version management

📊 Bulk Operations

• Bulk edit issues
• Bulk watch/unwatch
• Async operation tracking

📈 Dashboards & JQL

• Dashboard management
• JQL validation & autocomplete
• Labels management

Runtime Environment (choose ONE)

Simpler installation, faster execution

Install Bun (one command):

Windows (PowerShell as Admin):

irm bun.sh/install.ps1 | iex

macOS / Linux:

curl -fsSL https://bun.sh/install | bash

More widely used, larger ecosystem

Requirements:

• Node.js ≥18.0.0 (Download)
• npm ≥8.0.0 (included with Node.js)

Jira Requirements

MCP-Compatible Client (one of)

• VS Code with GitHub Copilot extension
• Claude Desktop app
• Cursor IDE
• Windsurf IDE
• Any other MCP-compatible AI assistant

🚀 Quick Start

Installation

# Run directly (no install needed)
bunx mcp-jira-cloud@latest

# Or install globally
bun install -g mcp-jira-cloud

# Run directly (no install needed)
npx -y mcp-jira-cloud@latest

# Or install globally
npm install -g mcp-jira-cloud

💡 CLI Help

To see all available options and configuration details:

npx -y mcp-jira-cloud@latest --help

To launch the interactive setup helper (generates MCP config JSON):

npx -y mcp-jira-cloud@latest --config

To verify your Jira connectivity and credentials:

npx -y mcp-jira-cloud@latest --verify

To enable diagnostic logging (logs API traffic to stderr):

npx -y mcp-jira-cloud@latest --verbose

Get Your API Token

1. Go to Atlassian API Tokens
2. Click Create API token
3. Copy the token

📘 VS Code (GitHub Copilot)

Create or edit .vscode/mcp.json in your workspace:

{
  "servers": {
    "jira": {
      "type": "stdio",
      "command": "bunx",
      "args": ["mcp-jira-cloud@latest"],
      "env": {
        "JIRA_BASE_URL": "https://your-domain.atlassian.net",
        "JIRA_EMAIL": "[email protected]",
        "JIRA_API_TOKEN": "your-api-token"
      }
    }
  }
}

{
  "servers": {
    "jira": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "mcp-jira-cloud@latest"],
      "env": {
        "JIRA_BASE_URL": "https://your-domain.atlassian.net",
        "JIRA_EMAIL": "[email protected]",
        "JIRA_API_TOKEN": "your-api-token"
      }
    }
  }
}

{
  "servers": {
    "jira": {
      "type": "stdio",
      "command": "jira-mcp",
      "args": [],
      "env": {
        "JIRA_BASE_URL": "https://your-domain.atlassian.net",
        "JIRA_EMAIL": "[email protected]",
        "JIRA_API_TOKEN": "your-api-token"
      }
    }
  }
}

🤖 Claude Desktop

Add to your Claude configuration (claude_desktop_config.json):

{
  "mcpServers": {
    "jira": {
      "command": "bunx",
      "args": ["mcp-jira-cloud@latest"],
      "env": {
        "JIRA_BASE_URL": "https://your-domain.atlassian.net",
        "JIRA_EMAIL": "[email protected]",
        "JIRA_API_TOKEN": "your-api-token"
      }
    }
  }
}

{
  "mcpServers": {
    "jira": {
      "command": "npx",
      "args": ["-y", "mcp-jira-cloud@latest"],
      "env": {
        "JIRA_BASE_URL": "https://your-domain.atlassian.net",
        "JIRA_EMAIL": "[email protected]",
        "JIRA_API_TOKEN": "your-api-token"
      }
    }
  }
}

⚡ Cursor

Create .cursor/mcp.json in your project or home directory:

{
  "mcpServers": {
    "jira": {
      "command": "bunx",
      "args": ["mcp-jira-cloud@latest"],
      "env": {
        "JIRA_BASE_URL": "https://your-domain.atlassian.net",
        "JIRA_EMAIL": "[email protected]",
        "JIRA_API_TOKEN": "your-api-token"
      }
    }
  }
}

{
  "mcpServers": {
    "jira": {
      "command": "npx",
      "args": ["-y", "mcp-jira-cloud@latest"],
      "env": {
        "JIRA_BASE_URL": "https://your-domain.atlassian.net",
        "JIRA_EMAIL": "[email protected]",
        "JIRA_API_TOKEN": "your-api-token"
      }
    }
  }
}

{
  "mcpServers": {
    "jira": {
      "command": "jira-mcp",
      "args": [],
      "env": {
        "JIRA_BASE_URL": "https://your-domain.atlassian.net",
        "JIRA_EMAIL": "[email protected]",
        "JIRA_API_TOKEN": "your-api-token"
      }
    }
  }
}

🔧 Windsurf

Add to your Windsurf MCP configuration:

{
  "mcpServers": {
    "jira": {
      "command": "bunx",
      "args": ["mcp-jira-cloud@latest"],
      "env": {
        "JIRA_BASE_URL": "https://your-domain.atlassian.net",
        "JIRA_EMAIL": "[email protected]",
        "JIRA_API_TOKEN": "your-api-token"
      }
    }
  }
}

{
  "mcpServers": {
    "jira": {
      "command": "npx",
      "args": ["-y", "mcp-jira-cloud@latest"],
      "env": {
        "JIRA_BASE_URL": "https://your-domain.atlassian.net",
        "JIRA_EMAIL": "[email protected]",
        "JIRA_API_TOKEN": "your-api-token"
      }
    }
  }
}

{
  "mcpServers": {
    "jira": {
      "command": "jira-mcp",
      "args": [],
      "env": {
        "JIRA_BASE_URL": "https://your-domain.atlassian.net",
        "JIRA_EMAIL": "[email protected]",
        "JIRA_API_TOKEN": "your-api-token"
      }
    }
  }
}

⚙️ Configuration

Environment Variables

Basic Authentication (Recommended)

OAuth 2.0 Authentication

For OAuth authentication:

1. Create an OAuth 2.0 app in the Atlassian Developer Console
2. Configure the required scopes:
   • read:jira-work
   • read:jira-user
   • write:jira-work
   • offline_access

Optional Settings

🛠️ Available Tools

91 tools organised into 11 categories

🔐 Authentication (7 tools)

📝 Issue CRUD (5 tools)

🔍 Issue Query (6 tools)

💬 Comments & Work Logs (5 tools)

⚙️ Configuration & Metadata (9 tools)

🛡️ Phase 14: Code Quality & Security

This release underwent a comprehensive audit to ensure best practices and security:

💡 Usage Examples

Once configured, interact with Jira through natural conversation:

Issue Management

👤 "What's the status of PROJ-123?"
🤖 Fetches and displays issue details, status, and assignee

👤 "Create a bug in PROJ for 'Login button not working'"
🤖 Creates a new bug issue and returns the issue key

👤 "Assign PROJ-456 to [email protected]"
🤖 Assigns the issue to the specified user

👤 "Move PROJ-789 to 'In Progress'"
🤖 Transitions the issue to the new status

Sprint & Agile

👤 "Show me the active sprint for board 123"
🤖 Displays current sprint details with dates and goal

👤 "Move PROJ-123 and PROJ-124 to sprint 456"
🤖 Moves the issues to the specified sprint

👤 "What's in the backlog for the PROJ board?"
🤖 Lists all backlog issues with priorities

Time Tracking

👤 "Log 2 hours on PROJ-456 for code review"
🤖 Creates work log entry with description

👤 "How much time has been logged on PROJ-789?"
🤖 Retrieves and summarises work logs

Collaboration

👤 "Link PROJ-123 as blocking PROJ-456"
🤖 Creates a "blocks" relationship between issues

👤 "Add me as a watcher on PROJ-789"
🤖 Adds you to the issue's watch list

👤 "Show all issues in epic PROJ-100"
🤖 Lists all child issues of the epic

🔧 Troubleshooting

Windows (PowerShell as Administrator):

# If irm fails, try:
Set-ExecutionPolicy RemoteSigned -Scope CurrentUser
irm bun.sh/install.ps1 | iex

macOS/Linux:

# If curl fails, check your internet connection or try:
brew install oven-sh/bun/bun  # macOS with Homebrew

Verify Installation:

bun --version  # Should show 1.x.x

Ensure your environment variables are correctly set. Verify with jira_auth_status.

Checklist:

• ✅ JIRA_BASE_URL includes https:// and is your full Jira domain
• ✅ JIRA_EMAIL matches your Atlassian account email
• ✅ JIRA_API_TOKEN is a valid, non-expired token

Your credentials are invalid or expired.

For Basic Auth:

• Verify your API token at Atlassian API Tokens
• Ensure the token hasn't been revoked

For OAuth:

• Try refreshing the token with jira_oauth_refresh
• Re-authenticate if the refresh token has expired

You don't have permission to access the requested resource.

Solutions:

• Check your Jira permissions for the project
• Contact your Jira administrator
• Verify your OAuth scopes include required permissions

The issue or project doesn't exist, or you don't have access to view it.

Solutions:

• Verify the issue key is correct (e.g., PROJ-123)
• Check if you have access to the project
• Ensure the issue hasn't been deleted or moved

Clear the cache to ensure you get the latest version:

npm:

npx -y --package=mcp-jira-cloud@latest mcp-jira-cloud
# or clear cache:
npm cache clean --force

Bun:

bunx --bun mcp-jira-cloud@latest
# or clear cache:
bun pm cache rm

📦 Package Information

Dependencies

🆕 What's New

🐛 v4.3.2 (Latest)

🚀 v4.3.0

🥟 v4.2.0

🔍 v4.1.0

🚀 v4.0.0

Total tools: 74

📦 v3.1.0

⚠️ v3.0.0 (Breaking Changes)

Removed for Safety:

• jira_delete_issue
• jira_delete_sprint
• jira_delete_attachment
• jira_delete_filter
• jira_delete_issue_link

Improvements:

• 🔒 Security patches (axios, qs)
• 🔄 Deprecated API migration
• ✅ 0 known vulnerabilities

v2.2.0

• Time Tracking Reports - Get user worklogs for any date range with summaries

v2.1.0

• Dashboard Management - View and manage Jira dashboards and gadgets
• Enhanced Attachments - Upload attachments, get metadata and content
• Labels Management - Get all labels, bulk add/remove/set labels
• JQL Tools - Autocomplete, validate, and parse JQL queries

v2.0.0

• Issue CRUD - Create, update issues with full field support
• Workflow Transitions - Move issues through workflow states
• Agile/Scrum - Complete sprint and board management (15 tools)
• Issue Linking - Blocks, relates, duplicates relationships
• Watchers & Voting - Collaboration features
• Epic Management - Organise issues under epics
• Filters - Create and manage saved JQL filters
• Metadata - Access field configurations and create metadata
• Bulk Operations - Edit, watch, unwatch multiple issues at once

🔒 Security

• Credentials are stored securely via system keychain (Keytar)
• OAuth tokens auto-refresh before expiration
• No credentials are logged or exposed in error messages
• See SECURITY.md for our security policy

🤝 Contributing

Contributions are welcome! Please see CONTRIBUTING.md for guidelines.

1. Fork the repository
2. Create a feature branch (git checkout -b feature/amazing-feature)
3. Commit your changes (git commit -m 'Add amazing feature')
4. Push to the branch (git push origin feature/amazing-feature)
5. Open a Pull Request

📄 Changelog

See CHANGELOG.md for a list of changes in each version.

📜 License

This project is licensed under the MIT License — see the LICENSE file for details.

🔗 Links