Jira MCP Server

A Model Context Protocol (MCP) server for Jira integration with OAuth authentication.

✨ Features

| Feature | Description | |---------|-------------| | 🛠️ 16 Tools | Tasks, sprints, comments, workload tracking | | 🔄 Sprint Integration | Auto-assign to active sprint | | 💬 Comments | Add & retrieve task comments | | 👤 Assignee | Update by email or account ID | | 🔐 OAuth | Auto-refresh tokens | | 🧪 Tested | 289 tests, 100% pass rate |

🚀 Quick Start

1. Install:

npm install -g @urcard/jira-mcp-server

2. Get credentials: Use OAuth Token Generator (easiest) or manual setup

3. Configure your IDE (see Configuration)

📋 Tools Overview

| Tool | Description | |------|-------------| | get_my_tasks | Get your tasks with filters (todo, in-progress, overdue, etc.) | | get_tasks_by_date | Tasks active on a date with daily hours | | search_tasks | Search by JQL or keyword | | create_task | Create task with subtasks & sprint assignment | | update_task | Update status, assignee, dates, story points | | update_task_dates | Update start/due dates | | update_story_points | Update story points | | get_task_details | Get task info with subtasks | | create_subtask | Create subtask for parent | | get_monthly_hours | Calculate monthly hours from story points | | get_board_sprints | List sprints for a board | | move_to_sprint | Move tasks to sprint | | get_sprint_tasks | All sprint tasks (team view) | | get_sprint_daily_tasks | In Progress tasks (daily standup) | | add_comment | Add comment to task | | get_comments | Get task comments |

⚙️ Configuration

Required Credentials

| Credential | Description | |------------|-------------| | access_token | OAuth access token | | refresh_token | OAuth refresh token | | client_id | OAuth client ID | | client_secret | OAuth client secret | | cloud_id | Atlassian Cloud ID |

Optional:

• default_project - Default project key (e.g., "URC")
• default_board_id - Board ID for auto-sprint (find in URL: /boards/9)

IDE Configuration

<details> <summary><b>Claude Desktop</b></summary>

Add to ~/Library/Application Support/Claude/claude_desktop_config.json:

{
  "mcpServers": {
    "jira": {
      "command": "jira-mcp-server",
      "args": [
        "--access_token", "YOUR_ACCESS_TOKEN",
        "--refresh_token", "YOUR_REFRESH_TOKEN",
        "--client_id", "YOUR_CLIENT_ID",
        "--client_secret", "YOUR_CLIENT_SECRET",
        "--cloud_id", "YOUR_CLOUD_ID",
        "--default_project", "YOUR_PROJECT",
        "--default_board_id", "YOUR_BOARD_ID"
      ]
    }
  }
}

</details> <details> <summary><b>Cursor</b></summary>

Create .cursor/mcp.json:

{
  "mcpServers": {
    "jira": {
      "command": "jira-mcp-server",
      "args": [
        "--access_token", "YOUR_ACCESS_TOKEN",
        "--refresh_token", "YOUR_REFRESH_TOKEN",
        "--client_id", "YOUR_CLIENT_ID",
        "--client_secret", "YOUR_CLIENT_SECRET",
        "--cloud_id", "YOUR_CLOUD_ID"
      ]
    }
  }
}

</details> <details> <summary><b>VS Code / Kiro</b></summary>

Add to settings or .vscode/mcp.json:

{
  "mcpServers": {
    "jira": {
      "command": "jira-mcp-server",
      "args": [
        "--access_token", "YOUR_ACCESS_TOKEN",
        "--refresh_token", "YOUR_REFRESH_TOKEN",
        "--client_id", "YOUR_CLIENT_ID",
        "--client_secret", "YOUR_CLIENT_SECRET",
        "--cloud_id", "YOUR_CLOUD_ID"
      ]
    }
  }
}

</details>

💡 Tip: Tokens are cached to ~/.jira-mcp/tokens.cache and auto-refresh. Configure once!

📖 Tool Examples

Task Management

// Get today's tasks
get_my_tasks({ filter: "today" })

// Create task with sprint assignment
create_task({
  project: "URC",
  summary: "New feature",
  storyPoints: 5,
  boardId: 9
})

// Update task status & assignee
update_task({
  taskKey: "URC-123",
  status: "In Progress",
  assignee: "john@example.com"
})

// Search tasks
search_tasks({ query: "project = URC AND status = Open" })

Sprint & Team

// Get sprint tasks for team
get_sprint_tasks({ boardId: 9 })

// Daily standup - In Progress tasks
get_sprint_daily_tasks({ boardId: 9 })

// Move tasks to sprint
move_to_sprint({ sprintId: 50, taskKeys: ["URC-1", "URC-2"] })

Comments

// Add comment
add_comment({ taskKey: "URC-123", body: "Working on this" })

// Get comments
get_comments({ taskKey: "URC-123", maxResults: 10 })

Workload

// Daily hours for a date
get_tasks_by_date({ date: "2025-01-15" })

// Monthly hours calculation
get_monthly_hours({ includeCompleted: true })

Field Selection

Reduce response size by selecting specific fields:

get_my_tasks({ 
  filter: "today", 
  fields: ["key", "summary", "status"] 
})

📊 Hours Calculation

Daily Hours: (Story Points × 2) ÷ Working Days

Monthly Hours: (Total Hours ÷ Total Working Days) × Days in Month

• Excludes weekends & Vietnamese holidays
• Handles cross-month tasks
• Avoids double-counting (excludes parents with subtasks)

🧪 Development

npm run dev          # Auto-reload
npm test             # Run 289 tests
npm run test:coverage # Coverage report
npm run lint         # Lint code

🔗 Links

• GitHub
• OAuth Token Generator
• MCP Protocol
• Issues

📄 License

MIT - Made with ❤️ by dongtran