Jira MCP Server v2.0

🎯 Complete Jira CLI integration via Model Context Protocol

This MCP server provides COMPLETE Jira integration through:

• Wrapping all Jira CLI commands
• Executing custom PowerShell reporting scripts
• Making direct REST API calls
• Supporting flexible workflow automation

🚀 Version 2.0 - Complete Feature Set

✨ NEW in v2.0:

• ⏱️ Worklog management (time tracking)
• 👁️ Watch/Unwatch issues
• 👍 Vote/Unvote for issues
• 🗑️ Issue deletion
• 📋 Issue clone/duplicate
• 🔗 Issue linking (blocks, relates to, etc.)
• 🏷️ Label management (add/remove)
• 🧩 Component management
• 🚀 Version/Release management
• 📎 Attachment support
• 🏃 Advanced sprint operations (add/remove issues)
• 🔄 Issue transitions list
• 📝 Subtask creation
• 💾 Issue export (CSV/JSON)

✨ Complete Feature List

🎯 Core Jira Operations

• ✅ Issue management: list, get, create, update, delete, clone
• ✅ Worklog management: add time, list worklogs
• ✅ Watch & Vote: watch/unwatch, vote/unvote
• ✅ Issue linking: link issues, view links
• ✅ Label management: add/remove labels
• ✅ Comments: add/list comments
• ✅ Transitions: list available status transitions
• ✅ Subtasks: create subtasks

📊 Project & Sprint Management

• ✅ Projects: list all projects
• ✅ Sprints: list, view sprint issues
• ✅ Sprint operations: add/remove issues from sprints
• ✅ Epics: list epics
• ✅ Boards: list all boards
• ✅ Components: list, create components
• ✅ Versions: list, create versions/releases

🔍 Advanced Features

• ✅ JQL queries: full JQL support with REST API
• ✅ Issue export: CSV and JSON export
• ✅ Attachments: add/list attachments
• ✅ Custom reports: Bug reports, recent issues (PowerShell)
• ✅ Browser integration: open issues directly in browser

🔧 Installation

Prerequisites

• Node.js >= 18.0.0
• Jira CLI installed (optional, for advanced features)
• PowerShell 5.1+ (Windows) or compatible shell
• Jira API credentials

Install Dependencies

cd jira-mcp-server
npm install

Configuration

Option 1: GitHub Package (Recommended)

Install directly from GitHub without publishing to npm:

{
  "mcpServers": {
    "JiraMCP": {
      "type": "stdio",
      "command": "npx",
      "args": [
        "@garyw/jira-mcp-server@latest"
      ],
      "env": {
        "JIRA_BASE_URL": "https://yourcompany.atlassian.net",
        "JIRA_USERNAME": "[email protected]",
        "JIRA_API_TOKEN": "YOUR_API_TOKEN_HERE",
        "JIRA_CLI_PATH": "/path/to/jira-cli/bin/jira"
      }
    }
  }
}

Option 2: Local Installation

Clone the repository and use a local path:

git clone https://github.com/garywenneker/jira-mcp-server.git
cd jira-mcp-server
npm install

Then configure:

{
  "mcpServers": {
    "JiraMCP": {
      "type": "stdio",
      "command": "node",
      "args": [
        "/path/to/jira-mcp-server/src/index.js"
      ],
      "env": {
        "JIRA_BASE_URL": "https://yourcompany.atlassian.net",
        "JIRA_USERNAME": "[email protected]",
        "JIRA_API_TOKEN": "YOUR_API_TOKEN_HERE",
        "PROJECT_ROOT": "/path/to/your/project",
        "JIRA_CLI_PATH": "/path/to/jira-cli/bin/jira"
      }
    }
  }
}

Option 3: Environment Variables (Most Secure)

Set credentials as environment variables instead of in config file:

export JIRA_BASE_URL="https://yourcompany.atlassian.net"
export JIRA_USERNAME="[email protected]"
export JIRA_API_TOKEN="YOUR_API_TOKEN_HERE"
export JIRA_CLI_PATH="/path/to/jira-cli/bin/jira"

Then use simplified config:

{
  "mcpServers": {
    "JiraMCP": {
      "type": "stdio",
      "command": "npx",
      "args": ["@garyw/jira-mcp-server@latest"]
    }
  }
}

⚠️ Security: Ensure your MCP config file is in .gitignore!

IDE Configuration Quick Start

Configure the Jira MCP server in your editor or AI assistant with the templates below.

Visual Studio Code (Continue)

Install the Continue copilot extension and add the server to .continue/config.json (or use the Continue settings UI):

{
  "mcpServers": {
    "jira-mcp": {
      "command": "node",
      "args": ["${workspaceFolder}/src/index.js"],
      "env": {
        "JIRA_BASE_URL": "https://yourcompany.atlassian.net",
        "JIRA_USERNAME": "[email protected]",
        "JIRA_API_TOKEN": "${env:JIRA_API_TOKEN}"
      }
    }
  }
}

Cursor IDE

Create or update .cursor/mcp-config.json in your repository:

{
  "mcpServers": {
    "JiraMCP": {
      "type": "stdio",
      "command": "npx",
      "args": ["@garyw/jira-mcp-server@latest"],
      "env": {
        "JIRA_BASE_URL": "https://yourcompany.atlassian.net",
        "JIRA_USERNAME": "[email protected]",
        "JIRA_API_TOKEN": "${env:JIRA_API_TOKEN}"
      }
    }
  }
}

JetBrains IDEs (AI Assistant)

Add a server entry in ~/.config/JetBrains/ai-assistant/mcp.json (Linux/macOS) or %APPDATA%\JetBrains\ai-assistant\mcp.json (Windows):

{
  "servers": {
    "jira": {
      "transport": "stdio",
      "command": "node",
      "args": ["/path/to/jira-mcp-server/src/index.js"],
      "env": {
        "JIRA_BASE_URL": "https://yourcompany.atlassian.net",
        "JIRA_USERNAME": "[email protected]",
        "JIRA_API_TOKEN": "${env:JIRA_API_TOKEN}"
      }
    }
  }
}

Claude Desktop & Web

Register the server in claude_desktop_config.json (Desktop) or the browser MCP settings panel:

{
  "mcpServers": {
    "jira": {
      "command": "npx",
      "args": ["@garyw/jira-mcp-server@latest"],
      "env": {
        "JIRA_BASE_URL": "https://yourcompany.atlassian.net",
        "JIRA_USERNAME": "[email protected]",
        "JIRA_API_TOKEN": "${env:JIRA_API_TOKEN}"
      }
    }
  }
}

Getting Your Jira API Token

1. Go to https://id.atlassian.com/manage-profile/security/api-tokens
2. Click "Create API token"
3. Give it a meaningful name
4. Copy the token and use it in your configuration

📚 Complete Tool Reference

🎯 Issue Management (15 tools)

jira_issue_list

List issues with filters.

Parameters:

• project (optional): Project key
• assignee (optional): Assignee
• status (optional): Status
• type (optional): Issue type
• limit (optional): Max results (default: 50)

jira_issue_get

Get detailed info of one issue.

Parameters:

• issue_key (required): Issue key

jira_issue_create

Create new issue.

Parameters:

• project (required): Project key
• type (required): Issue type
• summary (required): Title
• description (optional): Description
• priority (optional): Priority
• assignee (optional): Assignee

jira_issue_update

Update existing issue.

Parameters:

• issue_key (required): Issue key
• status (optional): New status
• assignee (optional): New assignee
• comment (optional): Add comment

jira_issue_delete

Delete an issue (⚠️ use with caution!).

Parameters:

• issue_key (required): Issue key

jira_issue_clone

Clone/duplicate an issue.

Parameters:

• issue_key (required): Issue to clone
• summary (optional): New summary

jira_issue_link

Link two issues together.

Parameters:

• from_issue (required): Source issue
• to_issue (required): Target issue
• link_type (required): Link type (e.g., 'blocks', 'relates to')

jira_issue_links

List all links of an issue.

Parameters:

• issue_key (required): Issue key

jira_issue_transitions

List available status transitions.

Parameters:

• issue_key (required): Issue key

jira_issue_watch

Watch an issue for notifications.

Parameters:

• issue_key (required): Issue key

jira_issue_unwatch

Stop watching an issue.

Parameters:

• issue_key (required): Issue key

jira_issue_vote

Vote for an issue.

Parameters:

• issue_key (required): Issue key

jira_issue_unvote

Remove your vote.

Parameters:

• issue_key (required): Issue key

jira_subtask_create

Create a subtask.

Parameters:

• parent_key (required): Parent issue
• summary (required): Subtask title
• description (optional): Description
• assignee (optional): Assignee

jira_issue_export

Export issues to CSV or JSON.

Parameters:

• jql (required): JQL query
• format (required): 'csv' or 'json'
• output_file (optional): Output file path
• maxResults (optional): Max results (default: 100)

⏱️ Worklog Management (2 tools)

jira_worklog_add

Add time to an issue.

Parameters:

• issue_key (required): Issue key
• time_spent (required): Time (e.g., '2h', '30m', '1d 4h')
• comment (optional): Worklog comment
• date (optional): Date of work (YYYY-MM-DD)

Example:

"Log 3 hours work on issue PROJ-123 with comment 'Implemented feature X'"

jira_worklog_list

List all worklogs for an issue.

Parameters:

• issue_key (required): Issue key

🏷️ Label Management (2 tools)

jira_label_add

Add labels to an issue.

Parameters:

• issue_key (required): Issue key
• labels (required): Comma-separated labels (e.g., 'frontend,bug,urgent')

Example:

"Add labels 'frontend' and 'high-priority' to PROJ-123"

jira_label_remove

Remove labels from an issue.

Parameters:

• issue_key (required): Issue key
• labels (required): Comma-separated labels

🧩 Component Management (2 tools)

jira_component_list

List components in a project.

Parameters:

• project (required): Project key

jira_component_add

Add a component to a project.

Parameters:

• project (required): Project key
• name (required): Component name
• description (optional): Description
• lead (optional): Component lead

🚀 Version/Release Management (2 tools)

jira_version_list

List versions/releases in a project.

Parameters:

• project (required): Project key

jira_version_create

Create a new version/release.

Parameters:

• project (required): Project key
• name (required): Version name (e.g., '1.0.0')
• description (optional): Description
• release_date (optional): Planned release date (YYYY-MM-DD)

📎 Attachment Tools (2 tools)

jira_attachment_add

Add an attachment to an issue.

Parameters:

• issue_key (required): Issue key
• file_path (required): Full file path

Example:

"Attach /path/to/screenshot.png to PROJ-123"

jira_attachment_list

List attachments of an issue.

Parameters:

• issue_key (required): Issue key

🏃 Advanced Sprint Operations (4 tools)

jira_sprint_list

List sprints for a board.

Parameters:

• board_name (optional): Board name
• state (optional): active, future, closed, all

jira_sprint_issues

Get issues from a sprint.

Parameters:

• sprint_name (required): Sprint name
• board_name (optional): Board name

jira_sprint_add_issue

Add issues to a sprint.

Parameters:

• sprint_name (required): Sprint name
• issue_keys (required): Comma-separated issue keys
• board_name (optional): Board name

Example:

"Add issues PROJ-100,PROJ-101,PROJ-102 to Sprint 42"

jira_sprint_remove_issue

Remove issues from a sprint.

Parameters:

• sprint_name (required): Sprint name
• issue_keys (required): Comma-separated issue keys
• board_name (optional): Board name

🔍 JQL & Reporting (3 tools)

jira_jql_query

Execute custom JQL query.

Parameters:

• jql (required): JQL query string
• maxResults (optional): Max results (default: 100)

Example JQL:

project = PROJ AND type = Bug AND status = "To Do" AND priority = High

jira_report_bugs

Comprehensive bug report with statistics.

Parameters:

• status (optional): Filter by status
• maxResults (optional): Max results (default: 100)
• outputFormat (optional): table, csv, json

jira_report_recent_issues

Recent issues overview (last N days).

Parameters:

• daysBack (optional): Days to look back (default: 7)
• maxResults (optional): Max results (default: 100)

📊 Project & Board Tools (4 tools)

jira_project_list

List all projects.

jira_epic_list

List epics in a project.

Parameters:

• project (optional): Project key filter

jira_board_list

List all boards.

Parameters:

• project (optional): Project key filter

🔧 Utility Tools (3 tools)

jira_open

Open issue in browser.

Parameters:

• issue_key (required): Issue key

jira_me

Show info about configured user.

jira_serverinfo

Show Jira server info.

💡 Usage Examples

Worklog Management

User: "Log 4 hours work on PROJ-3475 with comment 'Implemented authentication'"
AI: → jira_worklog_add(
      issue_key="PROJ-3475",
      time_spent="4h",
      comment="Implemented authentication"
    )
    → ✅ Worklog added

Sprint Planning

User: "Add issues PROJ-100 through PROJ-105 to current sprint"
AI: → jira_sprint_add_issue(
      sprint_name="Sprint 42",
      issue_keys="PROJ-100,PROJ-101,PROJ-102,PROJ-103,PROJ-104,PROJ-105"
    )
    → ✅ 6 issues added to sprint

Issue Linking

User: "Link PROJ-200 blocks PROJ-201"
AI: → jira_issue_link(
      from_issue="PROJ-200",
      to_issue="PROJ-201",
      link_type="blocks"
    )
    → ✅ Issues linked

Label Management

User: "Add labels 'frontend', 'bug' and 'urgent' to PROJ-150"
AI: → jira_label_add(
      issue_key="PROJ-150",
      labels="frontend,bug,urgent"
    )
    → ✅ Labels added

Issue Export

User: "Export all bugs from last month to CSV"
AI: → jira_issue_export(
      jql="type = Bug AND created >= -30d",
      format="csv",
      output_file="/path/to/bugs-export.csv"
    )
    → ✅ 47 issues exported

🔍 JQL Query Examples

# My open issues
assignee = currentUser() AND status != Done

# Bugs in current sprint
project = PROJ AND type = Bug AND sprint in openSprints()

# High priority issues this week
priority = High AND created >= -7d

# Issues with specific labels
labels in (frontend, urgent) AND status != Done

# Unassigned bugs
type = Bug AND assignee is EMPTY

# Issues with attachments
attachments is not EMPTY

# Issues without Epic
"Epic Link" is EMPTY

# Overdue issues
due < now() AND status != Done

# Recently updated issues
updated >= -24h

# Blocked issues
status = Blocked OR statusCategory = "To Do"

🔒 Security

Credentials Management

• ⚠️ NEVER commit API tokens to Git
• Store tokens in environment variables or password manager
• Add MCP config file to .gitignore
• Rotate tokens every 3-6 months
• Use minimal permissions

🐛 Troubleshooting

"401 Unauthorized"

Fix:

1. Generate new API token
2. Update JIRA_API_TOKEN in config
3. Restart application

"403 Forbidden"

Fix:

• Check Jira project permissions
• Verify account has Browse/Edit permissions
• Ask admin for access

"Jira CLI not found"

Fix:

• Verify JIRA_CLI_PATH is correct
• Check Jira CLI is installed: jira version
• Update path in config

"Invalid JQL query"

Fix:

• Test JQL in Jira UI (Filters → Advanced search)
• Check syntax: field names, operators
• Verify project keys and field names

"Command timeout"

Fix:

• Reduce maxResults parameter
• Simplify JQL query
• Check network connection

📊 Performance

• Caching: No caching (always fresh data)
• Rate Limiting: Follows Jira API rate limits
• Buffer Size: 10MB per command
• Timeout: 60 seconds per operation

🚀 Usage

Standalone Mode

npm start

Development Mode (auto-reload)

npm run dev

Via Cursor or Claude Desktop (MCP Integration)

Configure in MCP config file and restart application.

📝 Changelog

Version 2.0.0 (2025-11-01)

• ✨ MAJOR UPDATE: Complete Jira CLI feature parity
• ✅ Worklog management (add, list)
• ✅ Watch/Unwatch issues
• ✅ Vote/Unvote issues
• ✅ Issue delete
• ✅ Issue clone
• ✅ Issue linking
• ✅ Label management (add, remove)
• ✅ Component management
• ✅ Version/Release management
• ✅ Attachment support
• ✅ Advanced sprint operations
• ✅ Issue transitions list
• ✅ Subtask creation
• ✅ Issue export (CSV/JSON)
• 📚 Complete documentation overhaul

Version 1.0.0 (2025-10-31)

• ✨ Initial release
• ✅ Basic issue management
• ✅ JQL query execution
• ✅ Project & sprint management
• ✅ Custom PowerShell reporting

🤝 Contributing

Contributions are welcome! For changes:

1. Test locally thoroughly
2. Update this README
3. Update version in package.json
4. Commit with clear message
5. Create pull request with description

📧 Support

Documentation: This README + inline code comments
Jira API Docs: https://developer.atlassian.com/cloud/jira/platform/rest/v3/
Jira CLI Docs: https://github.com/ankitpokhrel/jira-cli

📄 License

MIT License - see LICENSE file for details

v2.0.0 - Complete Jira CLI Integration ✨

Made with ❤️ for the MCP community