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?

Without MCP	With Jira MCP
Switch between IDE and browser	Stay in your coding environment
Manual copy-paste of issue details	AI fetches context automatically
Learn JQL syntax	Natural language queries
Click through Jira UI	Voice/text commands
Context switching kills productivity	Seamless workflow integration

Supported AI Assistants

Assistant	Status
GitHub Copilot (VS Code)	✅ Fully Supported
Claude Desktop	✅ Fully Supported
Cursor	✅ Fully Supported
Windsurf	✅ Fully Supported
Any MCP-compatible client	✅ Fully Supported

✨ 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

📋 Prerequisites

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

Requirement	Notes
Jira Cloud	Jira Server/Data Center not supported
Atlassian Account	With access to your Jira instance
API Token	Generate here

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

Go to Atlassian API Tokens
Click Create API token
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": "your-email@example.com",
        "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": "your-email@example.com",
        "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": "your-email@example.com",
        "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": "your-email@example.com",
        "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": "your-email@example.com",
        "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": "your-email@example.com",
        "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": "your-email@example.com",
        "JIRA_API_TOKEN": "your-api-token"
      }
    }
  }
}

{
  "mcpServers": {
    "jira": {
      "command": "jira-mcp",
      "args": [],
      "env": {
        "JIRA_BASE_URL": "https://your-domain.atlassian.net",
        "JIRA_EMAIL": "your-email@example.com",
        "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": "your-email@example.com",
        "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": "your-email@example.com",
        "JIRA_API_TOKEN": "your-api-token"
      }
    }
  }
}

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

⚙️ Configuration

Environment Variables

Basic Authentication (Recommended)

Variable	Description	Required
`JIRA_BASE_URL`	Your Jira instance URL (e.g., `https://company.atlassian.net`)	✅
`JIRA_EMAIL`	Your Atlassian account email	✅
`JIRA_API_TOKEN`	API token from Atlassian	✅

OAuth 2.0 Authentication

For OAuth authentication:

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

Variable	Description	Required
`JIRA_OAUTH_CLIENT_ID`	OAuth Client ID	✅
`JIRA_OAUTH_CLIENT_SECRET`	OAuth Client Secret	✅
`JIRA_OAUTH_ACCESS_TOKEN`	Access token	✅
`JIRA_OAUTH_REFRESH_TOKEN`	Refresh token	⬜
`JIRA_CLOUD_ID`	Your Jira Cloud ID	✅

Optional Settings

Variable	Description	Default
`JIRA_ACCEPTANCE_CRITERIA_FIELD`	Custom field ID for acceptance criteria	—

🛠️ Available Tools

91 tools organised into 11 categories

🔐 Authentication (7 tools)

Tool	Description
`jira_auth_status`	Check current authentication status
`jira_whoami`	Get current user's Jira profile
`jira_clear_auth`	Clear stored credentials
`jira_oauth_get_auth_url`	Generate OAuth authorisation URL
`jira_oauth_exchange_code`	Exchange OAuth code for tokens
`jira_oauth_refresh`	Manually refresh OAuth token
`jira_oauth_list_sites`	List accessible Jira sites

📝 Issue CRUD (5 tools)

Tool	Description
`jira_create_issue`	Create a new issue with full field support
`jira_update_issue`	Update issue fields (partial update supported)
`jira_assign_issue`	Assign or unassign a user
`jira_get_transitions`	Get available workflow transitions
`jira_transition_issue`	Move issue through workflow states

🔍 Issue Query (6 tools)

Tool	Description
`jira_get_issue`	Get full details of a Jira issue (labels, status, priority, assignee, components, …); pass `fields` to return a specific subset
`jira_get_issue_summary`	Get summary, description, and acceptance criteria
`jira_search_issues`	Search issues with JQL, returning full field details (pass `fields` for a specific subset)
`jira_search_issues_summary`	Search with minimal fields (key, summary, status)
`jira_get_my_open_issues`	Get your open/in-progress issues
`jira_resolve`	Smart routing tool for common intents

💬 Comments & Work Logs (5 tools)

Tool	Description
`jira_get_issue_comments`	Get comments on an issue
`jira_add_comment`	Add a comment to an issue
`jira_add_worklog`	Log time spent on an issue
`jira_get_issue_worklogs`	Get work logs for an issue
`jira_get_user_worklogs`	Get worklogs by user and date range

⚙️ Configuration & Metadata (9 tools)

Tool	Description
`jira_list_projects`	List accessible Jira projects
`jira_get_project`	Get project details and metadata
`jira_get_issue_types`	Get available issue types
`jira_get_priorities`	Get priority levels
`jira_get_statuses`	Get available statuses
`jira_get_components`	Get project components
`jira_get_versions`	Get project versions
`jira_search_users`	Search for Jira users
`jira_get_changelog`	Get issue change history

Tool	Description
`jira_get_boards`	List Scrum and Kanban boards
`jira_get_board`	Get board details
`jira_get_board_configuration`	Get board configuration (columns, estimation)
`jira_get_sprints`	Get sprints for a board
`jira_get_sprint`	Get sprint details
`jira_create_sprint`	Create a new sprint
`jira_update_sprint`	Update sprint details
`jira_start_sprint`	Start a future sprint
`jira_complete_sprint`	Complete an active sprint
`jira_get_sprint_issues`	Get issues in a sprint
`jira_move_issues_to_sprint`	Move issues to a sprint
`jira_get_backlog_issues`	Get backlog issues for a board
`jira_move_issues_to_backlog`	Move issues to backlog
`jira_rank_issues`	Change issue ranking

Tool	Description
`jira_get_issue_links`	Get linked issues
`jira_create_issue_link`	Link two issues together
`jira_get_link_types`	Get available link types
`jira_get_watchers`	Get issue watchers
`jira_add_watcher`	Add a watcher to an issue
`jira_remove_watcher`	Remove a watcher
`jira_get_votes`	Get issue vote count
`jira_add_vote`	Vote for an issue
`jira_remove_vote`	Remove your vote

Tool	Description
`jira_get_epics`	Get epics for a board
`jira_get_epic_issues`	Get issues belonging to an epic
`jira_move_issues_to_epic`	Move issues to an epic
`jira_remove_issues_from_epic`	Remove issues from an epic

Tool	Description
`jira_get_fields`	Get all available fields (including custom)
`jira_get_create_metadata`	Get metadata for creating issues
`jira_get_edit_metadata`	Get metadata for editing issues

Tool	Description
`jira_get_filters`	Search saved filters
`jira_get_filter`	Get filter details
`jira_create_filter`	Create a new saved filter
`jira_update_filter`	Update an existing filter
`jira_get_my_filters`	Get filters owned by you
`jira_get_favourite_filters`	Get favourite filters

Tool	Description
`jira_bulk_edit_issues`	Edit multiple issues at once (labels, assignee, priority, etc.)
`jira_bulk_watch_issues`	Add watchers to multiple issues
`jira_bulk_unwatch_issues`	Remove watchers from multiple issues
`jira_get_bulk_operation_progress`	Track async bulk operation progress

Tool	Description
`jira_get_dashboards`	Get dashboards (filter by favourite/owned)
`jira_search_dashboards`	Search dashboards by name, owner, etc.
`jira_get_dashboard`	Get dashboard details by ID
`jira_get_dashboard_gadgets`	Get all gadgets on a dashboard
`jira_add_dashboard_gadget`	Add a gadget to a dashboard

Tool	Description
`jira_get_attachments`	Get issue attachments
`jira_upload_attachment`	Upload a file to an issue
`jira_get_attachment_metadata`	Get attachment metadata by ID
`jira_get_attachment_content`	Get attachment download URL

Tool	Description
`jira_get_all_labels`	Get all labels in the Jira instance
`jira_add_labels`	Add, set, or remove labels on an issue

Tool	Description
`jira_autocomplete_jql`	Get autocomplete suggestions for JQL fields
`jira_validate_jql`	Validate JQL queries for syntax errors
`jira_parse_jql`	Parse JQL into abstract syntax tree

Tool	Description
`jira_get_updated_worklog_ids`	Get worklog IDs created/updated since a date
`jira_get_worklogs_by_ids`	Get full worklog details by IDs (batch up to 1000)
`jira_get_user_worklogs`	Get all worklogs for a user in a date range with summary
`jira_get_deleted_worklog_ids`	Get IDs of deleted worklogs for audit purposes

🛡️ Phase 14: Code Quality & Security

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

Category	Status	Details
API Version	✅	All 91 tools use Jira REST API v3 (latest)
Agile API	✅	Sprint/Board tools use Jira Agile API v1.0
Deprecated APIs	✅	All deprecated endpoints migrated to modern alternatives
Security Vulnerabilities	✅	0 vulnerabilities (axios & qs patched)
OAuth 2.0 Support	✅	Full OAuth 2.0 (3LO) with auto-refresh
Credential Storage	✅	OS-level encryption via Keytar
Input Validation	✅	Zod v4 schema validation on all parameters
URL Encoding	✅	All dynamic path parameters properly encoded
Error Handling	✅	Consistent error handling across all endpoints

💡 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 john@example.com"
🤖 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

Attribute	Value
Package name	`mcp-jira-cloud`
Latest Version
License	MIT
Runtime	Bun ≥1.0.0 or Node.js ≥18.0.0
TypeScript	≥5.0.0
Module	ES Modules
Tools	91

Dependencies

Package	Purpose
`@modelcontextprotocol/sdk`	MCP protocol implementation
`axios`	HTTP client for Jira API
`keytar`	Secure credential storage
`zod`	Schema validation

🆕 What's New

🐛 v4.3.2 (Latest)

Fix	Description
🏷️ Full field passthrough	`jira_get_issue` & `jira_search_issues` now return every requested field — `labels`, `status`, `priority`, `assignee`, `components`, `fixVersions`, custom fields, etc. — instead of only `key`/`summary`/`description` (#2)
📋 Useful defaults	When `fields` is omitted, the full-detail tools now return a broad default set; lean summary tools keep their trimmed output
🧹 Compact, no fabrication	Nested objects are normalized to friendly values (`status`→name, `assignee`→display name, …) and unrequested fields are never invented

🚀 v4.3.0

Feature	Description
🧩 Modular Architecture	Tools refactored into modular, organized files (`src/tools/`)
🚀 Expanded Toolset	Now 91 tools, including new Agile, Worklog, and Metadata functions
🛡️ Improved Tooling	Standardized authentication (`withClient`) & annotation presets
✅ Test Suite	Integrated Vitest for robust unit testing across the codebase

🥟 v4.2.0

Feature	Description
🥟 Bun Support	Run with `bunx mcp-jira-cloud@latest` - easier for beginners
📖 Better Docs	Simplified prerequisites and configuration examples

🔍 v4.1.0

Feature	Description
🎯 Improved Tool Descriptions	Better trigger phrases, negative guidance, and cross-references for AI agents
📋 Prerequisites Section	Clear requirements documented in README

🚀 v4.0.0

Change	Description
⚠️ Breaking	`jira_get_worklogs` renamed to `jira_get_issue_worklogs` for clarity
🐛 Fix	Removed duplicate tool registration that caused startup errors

Total tools: 74

📦 v3.1.0

Feature	Description
🔍 User Worklogs Query	New `jira_get_user_worklogs` tool to query worklogs by user and date range
📊 Time Summary	Returns total time logged with formatted hours/minutes

⚠️ 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.

Fork the repository
Create a feature branch (git checkout -b feature/amazing-feature)
Commit your changes (git commit -m 'Add amazing feature')
Push to the branch (git push origin feature/amazing-feature)
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

Resource	Link
GitHub	github.com/tezaswiraj7222/jira-mcp
npm	npmjs.com/package/mcp-jira-cloud
Issues	Report a bug
MCP Protocol	modelcontextprotocol.io
Jira API	Jira REST API v3