Jira MCP Server

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

Features

• ✅ 14 Powerful Tools - Complete task management with sprint support & team workload tracking
• ✅ Sprint Integration - Auto-assign tasks to active sprint via boardId
• ✅ OAuth Authentication - Secure auto-refresh tokens
• ✅ Zero Configuration - No database, CLI-based setup
• ✅ MCP Compatible - Works with Claude, Cursor, VS Code

Installation

Global install (recommended):

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

Or clone from source:

git clone https://github.com/dongitran/Jira-MCP-Server.git
cd Jira-MCP-Server
npm install

Prerequisites

You need Jira OAuth credentials:

• 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 but recommended:

• default_project - Default project key (e.g., "URC") - no need to specify project every time
• default_board_id - Default board ID for auto-sprint assignment (e.g., "9")

🚀 Easy way to get credentials: Use our OAuth Token Generator - it provides ready-to-use MCP config with all required credentials including cloud_id!

Or manually: How to get Jira OAuth credentials →

Configuration

Quick Setup (Recommended)

Use our OAuth Token Generator to get ready-to-use config with all credentials including cloud_id. Just copy and paste!

For Claude Desktop

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

{
  "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_KEY",
        "--default_board_id", "YOUR_BOARD_ID"
      ],
      "env": {}
    }
  }
}

Note: default_project and default_board_id are optional. When set, tasks will auto-assign to the active sprint without specifying project/board each time. Board ID can be found in URL: /boards/9 → board_id = 9.

For Cursor

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"
      ],
      "env": {}
    }
  }
}

For VS Code

Add to ~/Library/Application Support/Code/User/mcp.json (macOS):

{
  "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"
      ],
      "env": {}
    }
  }
}

Note: After first run, tokens are cached to ~/.jira-mcp/tokens.cache and will auto-refresh. You only need to provide credentials once!

Available Tools

Field Selection (All Query Tools)

Most query tools support an optional fields parameter to return only specific fields, reducing response size and saving tokens for AI/LLM usage.

Example - Return only key and summary:

{
  "filter": "today",
  "fields": ["key", "summary"]
}

Without fields parameter: Returns all available fields (default behavior)

1. get_my_tasks

Get tasks assigned to current user with filters.

Parameters:

• filter: todo | today | in-progress | high-priority | overdue | completed | all
• period: today | week | month (for completed filter)
• fields: (optional) Array of fields to return. Available: key, summary, status, priority, dueDate, url

Example:

{
  "filter": "today"
}

2. get_tasks_by_date

Get tasks active on a specific date with daily hours calculation.

Parameters:

• date: Date in YYYY-MM-DD format

Example:

{
  "date": "2025-01-15"
}

Features:

• Calculates daily hours based on story points
• Excludes weekends and Vietnamese holidays
• Smart workload distribution

3. search_tasks

Search tasks using JQL query or keyword.

Parameters:

• query: JQL query or keyword
• maxResults: Maximum results (default: 50)

Example:

{
  "query": "project = URC AND status = 'In Progress'",
  "maxResults": 20
}

4. create_task

Create a new Jira task with optional subtasks and sprint assignment.

Parameters:

• project: Project key (required)
• summary: Task title (required)
• description: Task description (optional)
• issueType: Issue type (default: "Task")
• priority: Priority (default: "Medium")
• storyPoints: Story points (optional)
• startDate: Start date YYYY-MM-DD (optional)
• dueDate: Due date YYYY-MM-DD (optional)
• sprintId: Sprint ID for direct assignment (optional)
• boardId: Board ID to auto-assign to active sprint (optional)
• subtasks: Array of subtasks (optional)

Example - Auto-assign to active sprint:

{
  "project": "URC",
  "summary": "Implement new feature",
  "priority": "High",
  "storyPoints": 5,
  "boardId": 9,
  "dueDate": "2025-01-20"
}

Example - With subtasks:

{
  "project": "URC",
  "summary": "Implement new feature",
  "priority": "High",
  "storyPoints": 5,
  "boardId": 9,
  "subtasks": [
    {
      "summary": "Design API",
      "storyPoints": 2
    }
  ]
}

Sprint Assignment Options:

• Use boardId to auto-assign to the active sprint of that board
• Use sprintId for direct sprint assignment
• Board ID can be found in URL: https://urbox.atlassian.net/jira/software/projects/URC/boards/9 → boardId = 9

5. update_task_dates

Update start date and/or due date of a task.

Parameters:

• taskKey: Task key (required)
• startDate: Start date YYYY-MM-DD (optional)
• dueDate: Due date YYYY-MM-DD (optional)

6. update_story_points

Update story points of a task.

Parameters:

• taskKey: Task key (required)
• storyPoints: Story points value (required)

7. update_task

Update task fields including status, title, description, dates, and story points. Status change uses workflow transitions.

Parameters:

• taskKey: Task key (required)
• status: Target status using workflow transitions (optional, e.g., "In Progress", "Done")
• title: Task title/summary (optional)
• description: Task description (optional)
• startDate: Start date YYYY-MM-DD (optional)
• dueDate: Due date YYYY-MM-DD (optional)
• storyPoints: Story points value (optional)
• comment: Comment to add when changing status (optional)

Example - Change status:

{
  "taskKey": "URC-123",
  "status": "In Progress"
}

Example - Change status with comment:

{
  "taskKey": "URC-123",
  "status": "Done",
  "comment": "Task completed"
}

Example - Update multiple fields:

{
  "taskKey": "URC-123",
  "status": "In Progress",
  "storyPoints": 8,
  "dueDate": "2025-12-01"
}

Note: Status transitions follow Jira workflow rules. If a transition is not available, the error message will show available transitions.

8. get_task_details

Get detailed information about a specific task including all subtasks.

Parameters:

• taskKey: Task key (required)

Example:

{
  "taskKey": "URC-123"
}

9. create_subtask

Create a new subtask for an existing parent task.

Parameters:

• parentTaskKey: Parent task key (required)
• summary: Subtask title (required)
• description: Subtask description (optional)
• storyPoints: Story points (optional)
• startDate: Start date YYYY-MM-DD (optional)
• dueDate: Due date YYYY-MM-DD (optional)

Example:

{
  "parentTaskKey": "URC-123",
  "summary": "Implement API endpoint",
  "storyPoints": 3,
  "dueDate": "2025-01-20"
}

10. get_monthly_hours

Calculate total monthly hours based on Story Points and working days.

Parameters:

• includeCompleted: Include completed tasks (default: true)

Example:

{
  "includeCompleted": true
}

Features:

• Calculates hours distribution across months
• Excludes weekends and Vietnamese holidays
• Handles tasks spanning multiple months
• Provides detailed breakdown per task

11. get_board_sprints

Get all sprints for a board. Useful to find board ID and sprint IDs.

Parameters:

• boardId: Board ID (required) - found in URL: /boards/9 → boardId = 9
• state: Sprint state filter: active, future, closed, or all (default: active)

Example:

{
  "boardId": 9,
  "state": "active"
}

Response includes:

• List of sprints with ID, name, state, start/end dates
• Active sprint highlighted for easy reference

12. move_to_sprint

Move one or more existing tasks to a specific sprint.

Parameters:

• sprintId: Sprint ID to move tasks to (required)
• taskKeys: Array of task keys to move (required)

Example:

{
  "sprintId": 123,
  "taskKeys": ["URC-100", "URC-101", "URC-102"]
}

13. get_sprint_tasks

Get all tasks in a sprint for all team members. Great for sprint overview and team workload analysis.

Parameters:

• boardId: Board ID to get active sprint (optional, uses default if set)
• sprintId: Sprint ID for specific sprint (optional, overrides boardId)
• status: Filter by status: all, todo, in-progress, done (default: all)

Example - Get all tasks in active sprint:

{
  "boardId": 9
}

Example - Get only in-progress tasks:

{
  "boardId": 9,
  "status": "in-progress"
}

Response includes:

• Sprint info (id, name, state, dates)
• All tasks with assignee, status, story points
• Team summary with task count and total story points per member

14. get_sprint_daily_tasks

Get In Progress tasks for all team members in a sprint. Perfect for daily standup meetings.

Parameters:

• boardId: Board ID to get active sprint (optional, uses default if set)
• sprintId: Sprint ID for specific sprint (optional, overrides boardId)

Example:

{
  "boardId": 9
}

Response includes:

• Sprint info and current date
• Team workload breakdown (task count per member)
• All In Progress tasks with nested In Progress subtasks
• Parent tasks count, standalone tasks count, subtasks count

Features:

• Shows only In Progress tasks (perfect for daily standup)
• Parent tasks In Progress with their In Progress subtasks nested
• Standalone tasks In Progress (no subtasks)
• Subtasks of non-In Progress parents are excluded
• Groups tasks by assignee for easy team overview

Daily & Monthly Hours Calculation

Daily Hours (get_tasks_by_date)

Calculates daily hours intelligently:

• Formula: Daily Hours = (Story Points × 2) ÷ Working Days
• Working Days: Monday-Friday, excluding Vietnamese holidays
• Story Points Logic: Excludes parent tasks with subtasks to avoid double counting

Example:

• Task: 5 story points
• Duration: 5 working days
• Daily Hours: (5 × 2) ÷ 5 = 2 hours/day

Monthly Hours (get_monthly_hours)

Calculates monthly hours distribution:

• Formula: Monthly Hours = (Total Hours ÷ Total Working Days) × Working Days in Month
• Cross-Month Tasks: Automatically calculates portion for current month
• Working Days: Monday-Friday, excluding Vietnamese holidays
• Completed Tasks: Optionally include/exclude

Example:

• Task: 10 story points, spans 20 working days
• Total Hours: 10 × 2 = 20 hours
• Current month has 10 working days for this task
• Monthly Hours: (20 ÷ 20) × 10 = 10 hours

Development

# Run with auto-reload
npm run dev

# Lint code
npm run lint

# Fix lint issues
npm run lint:fix

Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

Links

• GitHub Repository
• OAuth Token Generator
• Model Context Protocol
• Jira Cloud Platform

Support

If you encounter any issues or have questions:

• Open an issue
• Check the MCP documentation

👨‍💻 Author

dongtran ✨

📄 License

MIT

Made with ❤️ to make your work life easier!