mcp-jira-cloud 2.2.0 → 3.0.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (7) hide show
  1. package/CHANGELOG.md +280 -172
  2. package/LICENSE +21 -21
  3. package/README.md +810 -799
  4. package/SECURITY.md +149 -149
  5. package/assets/logo.svg +30 -30
  6. package/dist/index.js +1 -1
  7. package/package.json +11 -8
package/README.md CHANGED
@@ -1,799 +1,810 @@
1
- <p align="center">
2
- <img src="https://cdn.jsdelivr.net/npm/mcp-jira-cloud@latest/assets/logo.svg" alt="Jira MCP Logo" width="120" height="120">
3
- </p>
4
-
5
- <h1 align="center">Jira MCP Server</h1>
6
-
7
- <p align="center">
8
- <strong>Supercharge your AI assistant with seamless Jira integration</strong>
9
- </p>
10
-
11
- <p align="center">
12
- <a href="https://www.npmjs.com/package/mcp-jira-cloud">
13
- <img src="https://img.shields.io/npm/v/mcp-jira-cloud?style=flat-square&color=cb3837&logo=npm" alt="npm version">
14
- </a>
15
- <a href="https://www.npmjs.com/package/mcp-jira-cloud">
16
- <img src="https://img.shields.io/npm/dm/mcp-jira-cloud?style=flat-square&color=blue" alt="npm downloads">
17
- </a>
18
- <a href="https://github.com/tezaswi7222/jira-mcp/blob/main/LICENSE">
19
- <img src="https://img.shields.io/npm/l/mcp-jira-cloud?style=flat-square&color=green" alt="license">
20
- </a>
21
- <a href="https://github.com/tezaswi7222/jira-mcp">
22
- <img src="https://img.shields.io/github/stars/tezaswi7222/jira-mcp?style=flat-square&logo=github" alt="GitHub stars">
23
- </a>
24
- </p>
25
-
26
- <p align="center">
27
- <a href="https://modelcontextprotocol.io/">
28
- <img src="https://img.shields.io/badge/MCP-Compatible-8A2BE2?style=flat-square" alt="MCP Compatible">
29
- </a>
30
- <a href="https://nodejs.org/">
31
- <img src="https://img.shields.io/badge/Node.js-18%2B-339933?style=flat-square&logo=node.js&logoColor=white" alt="Node.js 18+">
32
- </a>
33
- <a href="https://www.typescriptlang.org/">
34
- <img src="https://img.shields.io/badge/TypeScript-5.0%2B-3178C6?style=flat-square&logo=typescript&logoColor=white" alt="TypeScript 5.0+">
35
- </a>
36
- </p>
37
-
38
- <p align="center">
39
- <a href="#-quick-start">Quick Start</a> •
40
- <a href="#-features">Features</a> •
41
- <a href="#%EF%B8%8F-configuration">Configuration</a> •
42
- <a href="#-available-tools">Tools</a> •
43
- <a href="#-usage-examples">Examples</a> •
44
- <a href="#-troubleshooting">Troubleshooting</a>
45
- </p>
46
-
47
- ---
48
-
49
- 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.
50
-
51
- ## 🎯 Why Use This Package?
52
-
53
- | Without MCP | With Jira MCP |
54
- |-------------|---------------|
55
- | Switch between IDE and browser | Stay in your coding environment |
56
- | Manual copy-paste of issue details | AI fetches context automatically |
57
- | Learn JQL syntax | Natural language queries |
58
- | Click through Jira UI | Voice/text commands |
59
- | Context switching kills productivity | Seamless workflow integration |
60
-
61
- ### Supported AI Assistants
62
-
63
- | Assistant | Status |
64
- |-----------|--------|
65
- | GitHub Copilot (VS Code) | ✅ Fully Supported |
66
- | Claude Desktop | ✅ Fully Supported |
67
- | Cursor | ✅ Fully Supported |
68
- | Windsurf | ✅ Fully Supported |
69
- | Any MCP-compatible client | ✅ Fully Supported |
70
-
71
- ## ✨ Features
72
-
73
- <table>
74
- <tr>
75
- <td>
76
-
77
- ### 🔐 Authentication
78
- - Basic Auth (API Token)
79
- - OAuth 2.0 with auto-refresh
80
- - Secure credential storage via Keytar
81
-
82
- </td>
83
- <td>
84
-
85
- ### 📋 Issue Management
86
- - Full CRUD operations
87
- - Workflow transitions
88
- - Search with JQL
89
-
90
- </td>
91
- </tr>
92
- <tr>
93
- <td>
94
-
95
- ### 🏃 Agile/Scrum
96
- - Sprint management (create, start, complete)
97
- - Board views (Scrum & Kanban)
98
- - Backlog & ranking
99
-
100
- </td>
101
- <td>
102
-
103
- ### 🔗 Relationships
104
- - Issue linking (blocks, relates, duplicates)
105
- - Watchers & voting
106
- - Epic management
107
-
108
- </td>
109
- </tr>
110
- <tr>
111
- <td>
112
-
113
- ### ⏱️ Time Tracking
114
- - Log work on issues
115
- - View work logs
116
- - Flexible time formats
117
-
118
- </td>
119
- <td>
120
-
121
- ### 🗄️ Filters & Metadata
122
- - Create/manage saved filters
123
- - Field metadata access
124
- - Component & version management
125
-
126
- </td>
127
- </tr>
128
- <tr>
129
- <td>
130
-
131
- ### 📊 Bulk Operations
132
- - Bulk edit issues
133
- - Bulk watch/unwatch
134
- - Async operation tracking
135
-
136
- </td>
137
- <td>
138
-
139
- ### 📈 Dashboards & JQL
140
- - Dashboard management
141
- - JQL validation & autocomplete
142
- - Labels management
143
-
144
- </td>
145
- </tr>
146
- </table>
147
-
148
- <p align="center">
149
- <strong>78 Tools</strong> for comprehensive Jira management
150
- </p>
151
-
152
- ## 🚀 Quick Start
153
-
154
- ### Installation
155
-
156
- ```bash
157
- npm install -g mcp-jira-cloud
158
- ```
159
-
160
- Or use directly with `npx`:
161
-
162
- ```bash
163
- npx mcp-jira-cloud
164
- ```
165
-
166
- ### Get Your API Token
167
-
168
- 1. Go to [Atlassian API Tokens](https://id.atlassian.com/manage-profile/security/api-tokens)
169
- 2. Click **Create API token**
170
- 3. Copy the token
171
-
172
- ### Configure Your AI Assistant
173
-
174
- There are two ways to run the MCP server:
175
-
176
- | Method | Command | Best For |
177
- |--------|---------|----------|
178
- | **npx** (no install) | `npx mcp-jira-cloud` | Quick setup, always latest version |
179
- | **Global install** | `jira-mcp` | Faster startup, offline usage |
180
-
181
- ---
182
-
183
- #### 📘 VS Code (GitHub Copilot)
184
-
185
- Create or edit `.vscode/mcp.json` in your workspace:
186
-
187
- **Using npx (recommended):**
188
- ```json
189
- {
190
- "servers": {
191
- "jira": {
192
- "type": "stdio",
193
- "command": "npx",
194
- "args": ["mcp-jira-cloud"],
195
- "env": {
196
- "JIRA_BASE_URL": "https://your-domain.atlassian.net",
197
- "JIRA_EMAIL": "your-email@example.com",
198
- "JIRA_API_TOKEN": "your-api-token"
199
- }
200
- }
201
- }
202
- }
203
- ```
204
-
205
- **After global install (`npm i -g mcp-jira-cloud`):**
206
- ```json
207
- {
208
- "servers": {
209
- "jira": {
210
- "type": "stdio",
211
- "command": "jira-mcp",
212
- "args": [],
213
- "env": {
214
- "JIRA_BASE_URL": "https://your-domain.atlassian.net",
215
- "JIRA_EMAIL": "your-email@example.com",
216
- "JIRA_API_TOKEN": "your-api-token"
217
- }
218
- }
219
- }
220
- }
221
- ```
222
-
223
- ---
224
-
225
- #### 🤖 Claude Desktop
226
-
227
- Add to your Claude configuration (`claude_desktop_config.json`):
228
-
229
- **Using npx (recommended):**
230
- ```json
231
- {
232
- "mcpServers": {
233
- "jira": {
234
- "command": "npx",
235
- "args": ["mcp-jira-cloud"],
236
- "env": {
237
- "JIRA_BASE_URL": "https://your-domain.atlassian.net",
238
- "JIRA_EMAIL": "your-email@example.com",
239
- "JIRA_API_TOKEN": "your-api-token"
240
- }
241
- }
242
- }
243
- }
244
- ```
245
-
246
- **After global install (`npm i -g mcp-jira-cloud`):**
247
- ```json
248
- {
249
- "mcpServers": {
250
- "jira": {
251
- "command": "jira-mcp",
252
- "args": [],
253
- "env": {
254
- "JIRA_BASE_URL": "https://your-domain.atlassian.net",
255
- "JIRA_EMAIL": "your-email@example.com",
256
- "JIRA_API_TOKEN": "your-api-token"
257
- }
258
- }
259
- }
260
- }
261
- ```
262
-
263
- ---
264
-
265
- #### ⚡ Cursor
266
-
267
- Create `.cursor/mcp.json` in your project or home directory:
268
-
269
- **Using npx (recommended):**
270
- ```json
271
- {
272
- "mcpServers": {
273
- "jira": {
274
- "command": "npx",
275
- "args": ["mcp-jira-cloud"],
276
- "env": {
277
- "JIRA_BASE_URL": "https://your-domain.atlassian.net",
278
- "JIRA_EMAIL": "your-email@example.com",
279
- "JIRA_API_TOKEN": "your-api-token"
280
- }
281
- }
282
- }
283
- }
284
- ```
285
-
286
- **After global install (`npm i -g mcp-jira-cloud`):**
287
- ```json
288
- {
289
- "mcpServers": {
290
- "jira": {
291
- "command": "jira-mcp",
292
- "args": [],
293
- "env": {
294
- "JIRA_BASE_URL": "https://your-domain.atlassian.net",
295
- "JIRA_EMAIL": "your-email@example.com",
296
- "JIRA_API_TOKEN": "your-api-token"
297
- }
298
- }
299
- }
300
- }
301
- ```
302
-
303
- ---
304
-
305
- #### 🔧 Windsurf
306
-
307
- Add to your Windsurf MCP configuration:
308
-
309
- **Using npx (recommended):**
310
- ```json
311
- {
312
- "mcpServers": {
313
- "jira": {
314
- "command": "npx",
315
- "args": ["mcp-jira-cloud"],
316
- "env": {
317
- "JIRA_BASE_URL": "https://your-domain.atlassian.net",
318
- "JIRA_EMAIL": "your-email@example.com",
319
- "JIRA_API_TOKEN": "your-api-token"
320
- }
321
- }
322
- }
323
- }
324
- ```
325
-
326
- **After global install (`npm i -g mcp-jira-cloud`):**
327
- ```json
328
- {
329
- "mcpServers": {
330
- "jira": {
331
- "command": "jira-mcp",
332
- "args": [],
333
- "env": {
334
- "JIRA_BASE_URL": "https://your-domain.atlassian.net",
335
- "JIRA_EMAIL": "your-email@example.com",
336
- "JIRA_API_TOKEN": "your-api-token"
337
- }
338
- }
339
- }
340
- }
341
- ```
342
-
343
- ## ⚙️ Configuration
344
-
345
- ### Environment Variables
346
-
347
- #### Basic Authentication (Recommended)
348
-
349
- | Variable | Description | Required |
350
- |----------|-------------|:--------:|
351
- | `JIRA_BASE_URL` | Your Jira instance URL (e.g., `https://company.atlassian.net`) | ✅ |
352
- | `JIRA_EMAIL` | Your Atlassian account email | ✅ |
353
- | `JIRA_API_TOKEN` | API token from Atlassian | ✅ |
354
-
355
- #### OAuth 2.0 Authentication
356
-
357
- <details>
358
- <summary>Click to expand OAuth configuration</summary>
359
-
360
- For OAuth authentication:
361
-
362
- 1. Create an OAuth 2.0 app in the [Atlassian Developer Console](https://developer.atlassian.com/console/myapps/)
363
- 2. Configure the required scopes:
364
- - `read:jira-work`
365
- - `read:jira-user`
366
- - `write:jira-work`
367
- - `offline_access`
368
-
369
- | Variable | Description | Required |
370
- |----------|-------------|:--------:|
371
- | `JIRA_OAUTH_CLIENT_ID` | OAuth Client ID | ✅ |
372
- | `JIRA_OAUTH_CLIENT_SECRET` | OAuth Client Secret | ✅ |
373
- | `JIRA_OAUTH_ACCESS_TOKEN` | Access token | ✅ |
374
- | `JIRA_OAUTH_REFRESH_TOKEN` | Refresh token | ⬜ |
375
- | `JIRA_CLOUD_ID` | Your Jira Cloud ID | ✅ |
376
-
377
- </details>
378
-
379
- #### Optional Settings
380
-
381
- | Variable | Description | Default |
382
- |----------|-------------|---------|
383
- | `JIRA_ACCEPTANCE_CRITERIA_FIELD` | Custom field ID for acceptance criteria | — |
384
-
385
- ## 🛠️ Available Tools
386
-
387
- > **78 tools** organised into 15 categories
388
-
389
- ### 🔐 Authentication (7 tools)
390
-
391
- | Tool | Description |
392
- |------|-------------|
393
- | `jira_auth_status` | Check current authentication status |
394
- | `jira_whoami` | Get current user's Jira profile |
395
- | `jira_clear_auth` | Clear stored credentials |
396
- | `jira_oauth_get_auth_url` | Generate OAuth authorisation URL |
397
- | `jira_oauth_exchange_code` | Exchange OAuth code for tokens |
398
- | `jira_oauth_refresh` | Manually refresh OAuth token |
399
- | `jira_oauth_list_sites` | List accessible Jira sites |
400
-
401
- ### 📝 Issue CRUD (6 tools)
402
-
403
- | Tool | Description |
404
- |------|-------------|
405
- | `jira_create_issue` | Create a new issue with full field support |
406
- | `jira_update_issue` | Update issue fields (partial update supported) |
407
- | `jira_delete_issue` | Delete an issue (with safety confirmation) |
408
- | `jira_assign_issue` | Assign or unassign a user |
409
- | `jira_get_transitions` | Get available workflow transitions |
410
- | `jira_transition_issue` | Move issue through workflow states |
411
-
412
- ### 🔍 Issue Query (6 tools)
413
-
414
- | Tool | Description |
415
- |------|-------------|
416
- | `jira_get_issue` | Get full details of a Jira issue |
417
- | `jira_get_issue_summary` | Get summary, description, and acceptance criteria |
418
- | `jira_search_issues` | Search issues with JQL (full results) |
419
- | `jira_search_issues_summary` | Search with minimal fields (key, summary, status) |
420
- | `jira_get_my_open_issues` | Get your open/in-progress issues |
421
- | `jira_resolve` | Smart routing tool for common intents |
422
-
423
- ### 💬 Comments & Work Logs (4 tools)
424
-
425
- | Tool | Description |
426
- |------|-------------|
427
- | `jira_get_issue_comments` | Get comments on an issue |
428
- | `jira_add_comment` | Add a comment to an issue |
429
- | `jira_add_worklog` | Log time spent on an issue |
430
- | `jira_get_worklogs` | Get work logs for an issue |
431
-
432
- ### ⚙️ Configuration & Metadata (9 tools)
433
-
434
- | Tool | Description |
435
- |------|-------------|
436
- | `jira_list_projects` | List accessible Jira projects |
437
- | `jira_get_project` | Get project details and metadata |
438
- | `jira_get_issue_types` | Get available issue types |
439
- | `jira_get_priorities` | Get priority levels |
440
- | `jira_get_statuses` | Get available statuses |
441
- | `jira_get_components` | Get project components |
442
- | `jira_get_versions` | Get project versions |
443
- | `jira_search_users` | Search for Jira users |
444
- | `jira_get_changelog` | Get issue change history |
445
-
446
- <details>
447
- <summary><strong>🏃 Agile/Sprint Tools (16 tools)</strong></summary>
448
-
449
- | Tool | Description |
450
- |------|-------------|
451
- | `jira_get_boards` | List Scrum and Kanban boards |
452
- | `jira_get_board` | Get board details |
453
- | `jira_get_board_configuration` | Get board configuration (columns, estimation) |
454
- | `jira_get_sprints` | Get sprints for a board |
455
- | `jira_get_sprint` | Get sprint details |
456
- | `jira_create_sprint` | Create a new sprint |
457
- | `jira_update_sprint` | Update sprint details |
458
- | `jira_start_sprint` | Start a future sprint |
459
- | `jira_complete_sprint` | Complete an active sprint |
460
- | `jira_delete_sprint` | Delete a sprint |
461
- | `jira_get_sprint_issues` | Get issues in a sprint |
462
- | `jira_move_issues_to_sprint` | Move issues to a sprint |
463
- | `jira_get_backlog_issues` | Get backlog issues for a board |
464
- | `jira_move_issues_to_backlog` | Move issues to backlog |
465
- | `jira_rank_issues` | Change issue ranking |
466
-
467
- </details>
468
-
469
- <details>
470
- <summary><strong>🔗 Issue Relationships (11 tools)</strong></summary>
471
-
472
- | Tool | Description |
473
- |------|-------------|
474
- | `jira_get_issue_links` | Get linked issues |
475
- | `jira_create_issue_link` | Link two issues together |
476
- | `jira_delete_issue_link` | Remove an issue link |
477
- | `jira_get_link_types` | Get available link types |
478
- | `jira_get_watchers` | Get issue watchers |
479
- | `jira_add_watcher` | Add a watcher to an issue |
480
- | `jira_remove_watcher` | Remove a watcher |
481
- | `jira_get_votes` | Get issue vote count |
482
- | `jira_add_vote` | Vote for an issue |
483
- | `jira_remove_vote` | Remove your vote |
484
-
485
- </details>
486
-
487
- <details>
488
- <summary><strong> Epic Management (4 tools)</strong></summary>
489
-
490
- | Tool | Description |
491
- |------|-------------|
492
- | `jira_get_epics` | Get epics for a board |
493
- | `jira_get_epic_issues` | Get issues belonging to an epic |
494
- | `jira_move_issues_to_epic` | Move issues to an epic |
495
- | `jira_remove_issues_from_epic` | Remove issues from an epic |
496
-
497
- </details>
498
-
499
- <details>
500
- <summary><strong>🗂️ Field Metadata (3 tools)</strong></summary>
501
-
502
- | Tool | Description |
503
- |------|-------------|
504
- | `jira_get_fields` | Get all available fields (including custom) |
505
- | `jira_get_create_metadata` | Get metadata for creating issues |
506
- | `jira_get_edit_metadata` | Get metadata for editing issues |
507
-
508
- </details>
509
-
510
- <details>
511
- <summary><strong>🗄️ Filters (7 tools)</strong></summary>
512
-
513
- | Tool | Description |
514
- |------|-------------|
515
- | `jira_get_filters` | Search saved filters |
516
- | `jira_get_filter` | Get filter details |
517
- | `jira_create_filter` | Create a new saved filter |
518
- | `jira_update_filter` | Update an existing filter |
519
- | `jira_delete_filter` | Delete a filter |
520
- | `jira_get_my_filters` | Get filters owned by you |
521
- | `jira_get_favourite_filters` | Get favourite filters |
522
-
523
- </details>
524
-
525
- <details>
526
- <summary><strong>⚡ Bulk Operations (4 tools)</strong></summary>
527
-
528
- | Tool | Description |
529
- |------|-------------|
530
- | `jira_bulk_edit_issues` | Edit multiple issues at once (labels, assignee, priority, etc.) |
531
- | `jira_bulk_watch_issues` | Add watchers to multiple issues |
532
- | `jira_bulk_unwatch_issues` | Remove watchers from multiple issues |
533
- | `jira_get_bulk_operation_progress` | Track async bulk operation progress |
534
-
535
- </details>
536
-
537
- <details>
538
- <summary><strong>📊 Dashboard Management (5 tools)</strong></summary>
539
-
540
- | Tool | Description |
541
- |------|-------------|
542
- | `jira_get_dashboards` | Get dashboards (filter by favourite/owned) |
543
- | `jira_search_dashboards` | Search dashboards by name, owner, etc. |
544
- | `jira_get_dashboard` | Get dashboard details by ID |
545
- | `jira_get_dashboard_gadgets` | Get all gadgets on a dashboard |
546
- | `jira_add_dashboard_gadget` | Add a gadget to a dashboard |
547
-
548
- </details>
549
-
550
- <details>
551
- <summary><strong>📎 Enhanced Attachments (5 tools)</strong></summary>
552
-
553
- | Tool | Description |
554
- |------|-------------|
555
- | `jira_get_attachments` | Get issue attachments |
556
- | `jira_delete_attachment` | Delete an attachment |
557
- | `jira_upload_attachment` | Upload a file to an issue |
558
- | `jira_get_attachment_metadata` | Get attachment metadata by ID |
559
- | `jira_get_attachment_content` | Get attachment download URL |
560
-
561
- </details>
562
-
563
- <details>
564
- <summary><strong>🏷️ Labels Management (2 tools)</strong></summary>
565
-
566
- | Tool | Description |
567
- |------|-------------|
568
- | `jira_get_all_labels` | Get all labels in the Jira instance |
569
- | `jira_add_labels` | Add, set, or remove labels on an issue |
570
-
571
- </details>
572
-
573
- <details>
574
- <summary><strong>🔎 JQL Tools (3 tools)</strong></summary>
575
-
576
- | Tool | Description |
577
- |------|-------------|
578
- | `jira_autocomplete_jql` | Get autocomplete suggestions for JQL fields |
579
- | `jira_validate_jql` | Validate JQL queries for syntax errors |
580
- | `jira_parse_jql` | Parse JQL into abstract syntax tree |
581
-
582
- </details>
583
-
584
- <details>
585
- <summary><strong>⏱️ Time Tracking Reports (4 tools)</strong></summary>
586
-
587
- | Tool | Description |
588
- |------|-------------|
589
- | `jira_get_updated_worklog_ids` | Get worklog IDs created/updated since a date |
590
- | `jira_get_worklogs_by_ids` | Get full worklog details by IDs (batch up to 1000) |
591
- | `jira_get_user_worklogs` | Get all worklogs for a user in a date range with summary |
592
- | `jira_get_deleted_worklog_ids` | Get IDs of deleted worklogs for audit purposes |
593
-
594
- </details>
595
-
596
- ## 💡 Usage Examples
597
-
598
- Once configured, interact with Jira through natural conversation:
599
-
600
- ### Issue Management
601
-
602
- ```
603
- 👤 "What's the status of PROJ-123?"
604
- 🤖 Fetches and displays issue details, status, and assignee
605
-
606
- 👤 "Create a bug in PROJ for 'Login button not working'"
607
- 🤖 Creates a new bug issue and returns the issue key
608
-
609
- 👤 "Assign PROJ-456 to john@example.com"
610
- 🤖 Assigns the issue to the specified user
611
-
612
- 👤 "Move PROJ-789 to 'In Progress'"
613
- 🤖 Transitions the issue to the new status
614
- ```
615
-
616
- ### Sprint & Agile
617
-
618
- ```
619
- 👤 "Show me the active sprint for board 123"
620
- 🤖 Displays current sprint details with dates and goal
621
-
622
- 👤 "Move PROJ-123 and PROJ-124 to sprint 456"
623
- 🤖 Moves the issues to the specified sprint
624
-
625
- 👤 "What's in the backlog for the PROJ board?"
626
- 🤖 Lists all backlog issues with priorities
627
- ```
628
-
629
- ### Time Tracking
630
-
631
- ```
632
- 👤 "Log 2 hours on PROJ-456 for code review"
633
- 🤖 Creates work log entry with description
634
-
635
- 👤 "How much time has been logged on PROJ-789?"
636
- 🤖 Retrieves and summarises work logs
637
- ```
638
-
639
- ### Collaboration
640
-
641
- ```
642
- 👤 "Link PROJ-123 as blocking PROJ-456"
643
- 🤖 Creates a "blocks" relationship between issues
644
-
645
- 👤 "Add me as a watcher on PROJ-789"
646
- 🤖 Adds you to the issue's watch list
647
-
648
- 👤 "Show all issues in epic PROJ-100"
649
- 🤖 Lists all child issues of the epic
650
- ```
651
-
652
- ## 🔧 Troubleshooting
653
-
654
- <details>
655
- <summary><strong>❌ "MISSING_AUTH" Error</strong></summary>
656
-
657
- Ensure your environment variables are correctly set. Verify with `jira_auth_status`.
658
-
659
- **Checklist:**
660
- - ✅ `JIRA_BASE_URL` includes `https://` and is your full Jira domain
661
- - ✅ `JIRA_EMAIL` matches your Atlassian account email
662
- - ✅ `JIRA_API_TOKEN` is a valid, non-expired token
663
-
664
- </details>
665
-
666
- <details>
667
- <summary><strong>❌ "401 Unauthorised" Error</strong></summary>
668
-
669
- Your credentials are invalid or expired.
670
-
671
- **For Basic Auth:**
672
- - Verify your API token at [Atlassian API Tokens](https://id.atlassian.com/manage-profile/security/api-tokens)
673
- - Ensure the token hasn't been revoked
674
-
675
- **For OAuth:**
676
- - Try refreshing the token with `jira_oauth_refresh`
677
- - Re-authenticate if the refresh token has expired
678
-
679
- </details>
680
-
681
- <details>
682
- <summary><strong>❌ "403 Forbidden" Error</strong></summary>
683
-
684
- You don't have permission to access the requested resource.
685
-
686
- **Solutions:**
687
- - Check your Jira permissions for the project
688
- - Contact your Jira administrator
689
- - Verify your OAuth scopes include required permissions
690
-
691
- </details>
692
-
693
- <details>
694
- <summary><strong>❌ "404 Not Found" Error</strong></summary>
695
-
696
- The issue or project doesn't exist, or you don't have access to view it.
697
-
698
- **Solutions:**
699
- - Verify the issue key is correct (e.g., `PROJ-123`)
700
- - Check if you have access to the project
701
- - Ensure the issue hasn't been deleted or moved
702
-
703
- </details>
704
-
705
- ## 📦 Package Information
706
-
707
- | Attribute | Value |
708
- |-----------|-------|
709
- | Package name | [`mcp-jira-cloud`](https://www.npmjs.com/package/mcp-jira-cloud) |
710
- | Version | **2.2.0** |
711
- | License | [MIT](LICENSE) |
712
- | Node.js | ≥18.0.0 |
713
- | TypeScript | ≥5.0.0 |
714
- | Module | ES Modules |
715
- | Tools | **78** |
716
-
717
- ### Dependencies
718
-
719
- | Package | Purpose |
720
- |---------|---------|
721
- | [`@modelcontextprotocol/sdk`](https://www.npmjs.com/package/@modelcontextprotocol/sdk) | MCP protocol implementation |
722
- | [`axios`](https://www.npmjs.com/package/axios) | HTTP client for Jira API |
723
- | [`keytar`](https://www.npmjs.com/package/keytar) | Secure credential storage |
724
- | [`zod`](https://www.npmjs.com/package/zod) | Schema validation |
725
-
726
- ## 🆕 What's New in v2.0.0
727
-
728
- <details>
729
- <summary><strong>Click to see full changelog</strong></summary>
730
-
731
- ### Added
732
- - **Issue CRUD** - Create, update, delete issues with full field support
733
- - **Workflow Transitions** - Move issues through workflow states
734
- - **Agile/Scrum** - Complete sprint and board management (16 tools)
735
- - **Issue Linking** - Blocks, relates, duplicates relationships
736
- - **Watchers & Voting** - Collaboration features
737
- - **Epic Management** - Organise issues under epics
738
- - **Filters** - Create and manage saved JQL filters
739
- - **Metadata** - Access field configurations and create metadata
740
- - **Bulk Operations** - Edit, watch, unwatch multiple issues at once
741
- - **Dashboard Management** - View and manage Jira dashboards and gadgets
742
- - **Enhanced Attachments** - Upload attachments, get metadata and content
743
- - **Labels Management** - Get all labels, bulk add/remove/set labels
744
- - **JQL Tools** - Autocomplete, validate, and parse JQL queries
745
- - **Time Tracking Reports** - Get user worklogs for any date range with summaries
746
-
747
- ### Changed
748
- - Total tools increased from 18 to 78
749
- - Improved TypeScript strict mode compliance
750
- - Enhanced error handling and validation
751
-
752
- </details>
753
-
754
- ## 🔒 Security
755
-
756
- - Credentials are stored securely via system keychain (Keytar)
757
- - OAuth tokens auto-refresh before expiration
758
- - No credentials are logged or exposed in error messages
759
- - See [SECURITY.md](SECURITY.md) for our security policy
760
-
761
- ## 🤝 Contributing
762
-
763
- Contributions are welcome! Please see [CONTRIBUTING.md](CONTRIBUTING.md) for guidelines.
764
-
765
- 1. Fork the repository
766
- 2. Create a feature branch (`git checkout -b feature/amazing-feature`)
767
- 3. Commit your changes (`git commit -m 'Add amazing feature'`)
768
- 4. Push to the branch (`git push origin feature/amazing-feature`)
769
- 5. Open a Pull Request
770
-
771
- ## 📄 Changelog
772
-
773
- See [CHANGELOG.md](CHANGELOG.md) for a list of changes in each version.
774
-
775
- ## 📜 License
776
-
777
- This project is licensed under the **MIT License** — see the [LICENSE](LICENSE) file for details.
778
-
779
- ## 🔗 Links
780
-
781
- | Resource | Link |
782
- |----------|------|
783
- | GitHub | [github.com/tezaswi7222/jira-mcp](https://github.com/tezaswi7222/jira-mcp) |
784
- | npm | [npmjs.com/package/mcp-jira-cloud](https://www.npmjs.com/package/mcp-jira-cloud) |
785
- | Issues | [Report a bug](https://github.com/tezaswi7222/jira-mcp/issues) |
786
- | MCP Protocol | [modelcontextprotocol.io](https://modelcontextprotocol.io/) |
787
- | Jira API | [Jira REST API v3](https://developer.atlassian.com/cloud/jira/platform/rest/v3/intro/) |
788
-
789
- ---
790
-
791
- <p align="center">
792
- Made with ❤️ by <a href="https://github.com/tezaswi7222">Tezaswi Raj (github: tezaswi7222)</a>
793
- </p>
794
-
795
- <p align="center">
796
- <a href="https://github.com/sponsors/tezaswi7222">
797
- <img src="https://img.shields.io/badge/Sponsor-❤️-ea4aaa?style=for-the-badge" alt="Sponsor">
798
- </a>
799
- </p>
1
+ <p align="center">
2
+ <img src="https://cdn.jsdelivr.net/npm/mcp-jira-cloud@latest/assets/logo.svg" alt="Jira MCP Logo" width="120" height="120">
3
+ </p>
4
+
5
+ <h1 align="center">Jira MCP Server</h1>
6
+
7
+ <p align="center">
8
+ <strong>Supercharge your AI assistant with seamless Jira integration</strong>
9
+ </p>
10
+
11
+ <p align="center">
12
+ <a href="https://www.npmjs.com/package/mcp-jira-cloud">
13
+ <img src="https://img.shields.io/npm/v/mcp-jira-cloud?style=flat-square&color=cb3837&logo=npm" alt="npm version">
14
+ </a>
15
+ <a href="https://www.npmjs.com/package/mcp-jira-cloud">
16
+ <img src="https://img.shields.io/npm/dm/mcp-jira-cloud?style=flat-square&color=blue" alt="npm downloads">
17
+ </a>
18
+ <a href="https://github.com/tezaswi7222/jira-mcp/blob/main/LICENSE">
19
+ <img src="https://img.shields.io/npm/l/mcp-jira-cloud?style=flat-square&color=green" alt="license">
20
+ </a>
21
+ <a href="https://github.com/tezaswi7222/jira-mcp">
22
+ <img src="https://img.shields.io/github/stars/tezaswi7222/jira-mcp?style=flat-square&logo=github" alt="GitHub stars">
23
+ </a>
24
+ </p>
25
+
26
+ <p align="center">
27
+ <a href="https://modelcontextprotocol.io/">
28
+ <img src="https://img.shields.io/badge/MCP-Compatible-8A2BE2?style=flat-square" alt="MCP Compatible">
29
+ </a>
30
+ <a href="https://nodejs.org/">
31
+ <img src="https://img.shields.io/badge/Node.js-18%2B-339933?style=flat-square&logo=node.js&logoColor=white" alt="Node.js 18+">
32
+ </a>
33
+ <a href="https://www.typescriptlang.org/">
34
+ <img src="https://img.shields.io/badge/TypeScript-5.0%2B-3178C6?style=flat-square&logo=typescript&logoColor=white" alt="TypeScript 5.0+">
35
+ </a>
36
+ </p>
37
+
38
+ <p align="center">
39
+ <a href="#-quick-start">Quick Start</a> •
40
+ <a href="#-features">Features</a> •
41
+ <a href="#%EF%B8%8F-configuration">Configuration</a> •
42
+ <a href="#-available-tools">Tools</a> •
43
+ <a href="#-usage-examples">Examples</a> •
44
+ <a href="#-troubleshooting">Troubleshooting</a>
45
+ </p>
46
+
47
+ ---
48
+
49
+ 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.
50
+
51
+ ## 🎯 Why Use This Package?
52
+
53
+ | Without MCP | With Jira MCP |
54
+ |-------------|---------------|
55
+ | Switch between IDE and browser | Stay in your coding environment |
56
+ | Manual copy-paste of issue details | AI fetches context automatically |
57
+ | Learn JQL syntax | Natural language queries |
58
+ | Click through Jira UI | Voice/text commands |
59
+ | Context switching kills productivity | Seamless workflow integration |
60
+
61
+ ### Supported AI Assistants
62
+
63
+ | Assistant | Status |
64
+ |-----------|--------|
65
+ | GitHub Copilot (VS Code) | ✅ Fully Supported |
66
+ | Claude Desktop | ✅ Fully Supported |
67
+ | Cursor | ✅ Fully Supported |
68
+ | Windsurf | ✅ Fully Supported |
69
+ | Any MCP-compatible client | ✅ Fully Supported |
70
+
71
+ ## ✨ Features
72
+
73
+ <table>
74
+ <tr>
75
+ <td>
76
+
77
+ ### 🔐 Authentication
78
+ - Basic Auth (API Token)
79
+ - OAuth 2.0 with auto-refresh
80
+ - Secure credential storage via Keytar
81
+
82
+ </td>
83
+ <td>
84
+
85
+ ### 📋 Issue Management
86
+ - Full CRUD operations
87
+ - Workflow transitions
88
+ - Search with JQL
89
+
90
+ </td>
91
+ </tr>
92
+ <tr>
93
+ <td>
94
+
95
+ ### 🏃 Agile/Scrum
96
+ - Sprint management (create, start, complete)
97
+ - Board views (Scrum & Kanban)
98
+ - Backlog & ranking
99
+
100
+ </td>
101
+ <td>
102
+
103
+ ### 🔗 Relationships
104
+ - Issue linking (blocks, relates, duplicates)
105
+ - Watchers & voting
106
+ - Epic management
107
+
108
+ </td>
109
+ </tr>
110
+ <tr>
111
+ <td>
112
+
113
+ ### ⏱️ Time Tracking
114
+ - Log work on issues
115
+ - View work logs
116
+ - Flexible time formats
117
+
118
+ </td>
119
+ <td>
120
+
121
+ ### 🗄️ Filters & Metadata
122
+ - Create/manage saved filters
123
+ - Field metadata access
124
+ - Component & version management
125
+
126
+ </td>
127
+ </tr>
128
+ <tr>
129
+ <td>
130
+
131
+ ### 📊 Bulk Operations
132
+ - Bulk edit issues
133
+ - Bulk watch/unwatch
134
+ - Async operation tracking
135
+
136
+ </td>
137
+ <td>
138
+
139
+ ### 📈 Dashboards & JQL
140
+ - Dashboard management
141
+ - JQL validation & autocomplete
142
+ - Labels management
143
+
144
+ </td>
145
+ </tr>
146
+ </table>
147
+
148
+ <p align="center">
149
+ <strong>73 Tools</strong> for comprehensive Jira management
150
+ </p>
151
+
152
+ ## 🚀 Quick Start
153
+
154
+ ### Installation
155
+
156
+ ```bash
157
+ npm install -g mcp-jira-cloud
158
+ ```
159
+
160
+ Or use directly with `npx`:
161
+
162
+ ```bash
163
+ npx mcp-jira-cloud
164
+ ```
165
+
166
+ ### Get Your API Token
167
+
168
+ 1. Go to [Atlassian API Tokens](https://id.atlassian.com/manage-profile/security/api-tokens)
169
+ 2. Click **Create API token**
170
+ 3. Copy the token
171
+
172
+ ### Configure Your AI Assistant
173
+
174
+ There are two ways to run the MCP server:
175
+
176
+ | Method | Command | Best For |
177
+ |--------|---------|----------|
178
+ | **npx** (no install) | `npx mcp-jira-cloud` | Quick setup, always latest version |
179
+ | **Global install** | `jira-mcp` | Faster startup, offline usage |
180
+
181
+ ---
182
+
183
+ #### 📘 VS Code (GitHub Copilot)
184
+
185
+ Create or edit `.vscode/mcp.json` in your workspace:
186
+
187
+ **Using npx (recommended):**
188
+ ```json
189
+ {
190
+ "servers": {
191
+ "jira": {
192
+ "type": "stdio",
193
+ "command": "npx",
194
+ "args": ["mcp-jira-cloud"],
195
+ "env": {
196
+ "JIRA_BASE_URL": "https://your-domain.atlassian.net",
197
+ "JIRA_EMAIL": "your-email@example.com",
198
+ "JIRA_API_TOKEN": "your-api-token"
199
+ }
200
+ }
201
+ }
202
+ }
203
+ ```
204
+
205
+ **After global install (`npm i -g mcp-jira-cloud`):**
206
+ ```json
207
+ {
208
+ "servers": {
209
+ "jira": {
210
+ "type": "stdio",
211
+ "command": "jira-mcp",
212
+ "args": [],
213
+ "env": {
214
+ "JIRA_BASE_URL": "https://your-domain.atlassian.net",
215
+ "JIRA_EMAIL": "your-email@example.com",
216
+ "JIRA_API_TOKEN": "your-api-token"
217
+ }
218
+ }
219
+ }
220
+ }
221
+ ```
222
+
223
+ ---
224
+
225
+ #### 🤖 Claude Desktop
226
+
227
+ Add to your Claude configuration (`claude_desktop_config.json`):
228
+
229
+ **Using npx (recommended):**
230
+ ```json
231
+ {
232
+ "mcpServers": {
233
+ "jira": {
234
+ "command": "npx",
235
+ "args": ["mcp-jira-cloud"],
236
+ "env": {
237
+ "JIRA_BASE_URL": "https://your-domain.atlassian.net",
238
+ "JIRA_EMAIL": "your-email@example.com",
239
+ "JIRA_API_TOKEN": "your-api-token"
240
+ }
241
+ }
242
+ }
243
+ }
244
+ ```
245
+
246
+ **After global install (`npm i -g mcp-jira-cloud`):**
247
+ ```json
248
+ {
249
+ "mcpServers": {
250
+ "jira": {
251
+ "command": "jira-mcp",
252
+ "args": [],
253
+ "env": {
254
+ "JIRA_BASE_URL": "https://your-domain.atlassian.net",
255
+ "JIRA_EMAIL": "your-email@example.com",
256
+ "JIRA_API_TOKEN": "your-api-token"
257
+ }
258
+ }
259
+ }
260
+ }
261
+ ```
262
+
263
+ ---
264
+
265
+ #### ⚡ Cursor
266
+
267
+ Create `.cursor/mcp.json` in your project or home directory:
268
+
269
+ **Using npx (recommended):**
270
+ ```json
271
+ {
272
+ "mcpServers": {
273
+ "jira": {
274
+ "command": "npx",
275
+ "args": ["mcp-jira-cloud"],
276
+ "env": {
277
+ "JIRA_BASE_URL": "https://your-domain.atlassian.net",
278
+ "JIRA_EMAIL": "your-email@example.com",
279
+ "JIRA_API_TOKEN": "your-api-token"
280
+ }
281
+ }
282
+ }
283
+ }
284
+ ```
285
+
286
+ **After global install (`npm i -g mcp-jira-cloud`):**
287
+ ```json
288
+ {
289
+ "mcpServers": {
290
+ "jira": {
291
+ "command": "jira-mcp",
292
+ "args": [],
293
+ "env": {
294
+ "JIRA_BASE_URL": "https://your-domain.atlassian.net",
295
+ "JIRA_EMAIL": "your-email@example.com",
296
+ "JIRA_API_TOKEN": "your-api-token"
297
+ }
298
+ }
299
+ }
300
+ }
301
+ ```
302
+
303
+ ---
304
+
305
+ #### 🔧 Windsurf
306
+
307
+ Add to your Windsurf MCP configuration:
308
+
309
+ **Using npx (recommended):**
310
+ ```json
311
+ {
312
+ "mcpServers": {
313
+ "jira": {
314
+ "command": "npx",
315
+ "args": ["mcp-jira-cloud"],
316
+ "env": {
317
+ "JIRA_BASE_URL": "https://your-domain.atlassian.net",
318
+ "JIRA_EMAIL": "your-email@example.com",
319
+ "JIRA_API_TOKEN": "your-api-token"
320
+ }
321
+ }
322
+ }
323
+ }
324
+ ```
325
+
326
+ **After global install (`npm i -g mcp-jira-cloud`):**
327
+ ```json
328
+ {
329
+ "mcpServers": {
330
+ "jira": {
331
+ "command": "jira-mcp",
332
+ "args": [],
333
+ "env": {
334
+ "JIRA_BASE_URL": "https://your-domain.atlassian.net",
335
+ "JIRA_EMAIL": "your-email@example.com",
336
+ "JIRA_API_TOKEN": "your-api-token"
337
+ }
338
+ }
339
+ }
340
+ }
341
+ ```
342
+
343
+ ## ⚙️ Configuration
344
+
345
+ ### Environment Variables
346
+
347
+ #### Basic Authentication (Recommended)
348
+
349
+ | Variable | Description | Required |
350
+ |----------|-------------|:--------:|
351
+ | `JIRA_BASE_URL` | Your Jira instance URL (e.g., `https://company.atlassian.net`) | ✅ |
352
+ | `JIRA_EMAIL` | Your Atlassian account email | ✅ |
353
+ | `JIRA_API_TOKEN` | API token from Atlassian | ✅ |
354
+
355
+ #### OAuth 2.0 Authentication
356
+
357
+ <details>
358
+ <summary>Click to expand OAuth configuration</summary>
359
+
360
+ For OAuth authentication:
361
+
362
+ 1. Create an OAuth 2.0 app in the [Atlassian Developer Console](https://developer.atlassian.com/console/myapps/)
363
+ 2. Configure the required scopes:
364
+ - `read:jira-work`
365
+ - `read:jira-user`
366
+ - `write:jira-work`
367
+ - `offline_access`
368
+
369
+ | Variable | Description | Required |
370
+ |----------|-------------|:--------:|
371
+ | `JIRA_OAUTH_CLIENT_ID` | OAuth Client ID | ✅ |
372
+ | `JIRA_OAUTH_CLIENT_SECRET` | OAuth Client Secret | ✅ |
373
+ | `JIRA_OAUTH_ACCESS_TOKEN` | Access token | ✅ |
374
+ | `JIRA_OAUTH_REFRESH_TOKEN` | Refresh token | ⬜ |
375
+ | `JIRA_CLOUD_ID` | Your Jira Cloud ID | ✅ |
376
+
377
+ </details>
378
+
379
+ #### Optional Settings
380
+
381
+ | Variable | Description | Default |
382
+ |----------|-------------|---------|
383
+ | `JIRA_ACCEPTANCE_CRITERIA_FIELD` | Custom field ID for acceptance criteria | — |
384
+
385
+ ## 🛠️ Available Tools
386
+
387
+ > **73 tools** organised into 14 categories
388
+
389
+ ### 🔐 Authentication (7 tools)
390
+
391
+ | Tool | Description |
392
+ |------|-------------|
393
+ | `jira_auth_status` | Check current authentication status |
394
+ | `jira_whoami` | Get current user's Jira profile |
395
+ | `jira_clear_auth` | Clear stored credentials |
396
+ | `jira_oauth_get_auth_url` | Generate OAuth authorisation URL |
397
+ | `jira_oauth_exchange_code` | Exchange OAuth code for tokens |
398
+ | `jira_oauth_refresh` | Manually refresh OAuth token |
399
+ | `jira_oauth_list_sites` | List accessible Jira sites |
400
+
401
+ ### 📝 Issue CRUD (5 tools)
402
+
403
+ | Tool | Description |
404
+ |------|-------------|
405
+ | `jira_create_issue` | Create a new issue with full field support |
406
+ | `jira_update_issue` | Update issue fields (partial update supported) |
407
+ | `jira_assign_issue` | Assign or unassign a user |
408
+ | `jira_get_transitions` | Get available workflow transitions |
409
+ | `jira_transition_issue` | Move issue through workflow states |
410
+
411
+ ### 🔍 Issue Query (6 tools)
412
+
413
+ | Tool | Description |
414
+ |------|-------------|
415
+ | `jira_get_issue` | Get full details of a Jira issue |
416
+ | `jira_get_issue_summary` | Get summary, description, and acceptance criteria |
417
+ | `jira_search_issues` | Search issues with JQL (full results) |
418
+ | `jira_search_issues_summary` | Search with minimal fields (key, summary, status) |
419
+ | `jira_get_my_open_issues` | Get your open/in-progress issues |
420
+ | `jira_resolve` | Smart routing tool for common intents |
421
+
422
+ ### 💬 Comments & Work Logs (4 tools)
423
+
424
+ | Tool | Description |
425
+ |------|-------------|
426
+ | `jira_get_issue_comments` | Get comments on an issue |
427
+ | `jira_add_comment` | Add a comment to an issue |
428
+ | `jira_add_worklog` | Log time spent on an issue |
429
+ | `jira_get_worklogs` | Get work logs for an issue |
430
+
431
+ ### ⚙️ Configuration & Metadata (9 tools)
432
+
433
+ | Tool | Description |
434
+ |------|-------------|
435
+ | `jira_list_projects` | List accessible Jira projects |
436
+ | `jira_get_project` | Get project details and metadata |
437
+ | `jira_get_issue_types` | Get available issue types |
438
+ | `jira_get_priorities` | Get priority levels |
439
+ | `jira_get_statuses` | Get available statuses |
440
+ | `jira_get_components` | Get project components |
441
+ | `jira_get_versions` | Get project versions |
442
+ | `jira_search_users` | Search for Jira users |
443
+ | `jira_get_changelog` | Get issue change history |
444
+
445
+ <details>
446
+ <summary><strong>🏃 Agile/Sprint Tools (15 tools)</strong></summary>
447
+
448
+ | Tool | Description |
449
+ |------|-------------|
450
+ | `jira_get_boards` | List Scrum and Kanban boards |
451
+ | `jira_get_board` | Get board details |
452
+ | `jira_get_board_configuration` | Get board configuration (columns, estimation) |
453
+ | `jira_get_sprints` | Get sprints for a board |
454
+ | `jira_get_sprint` | Get sprint details |
455
+ | `jira_create_sprint` | Create a new sprint |
456
+ | `jira_update_sprint` | Update sprint details |
457
+ | `jira_start_sprint` | Start a future sprint |
458
+ | `jira_complete_sprint` | Complete an active sprint |
459
+ | `jira_get_sprint_issues` | Get issues in a sprint |
460
+ | `jira_move_issues_to_sprint` | Move issues to a sprint |
461
+ | `jira_get_backlog_issues` | Get backlog issues for a board |
462
+ | `jira_move_issues_to_backlog` | Move issues to backlog |
463
+ | `jira_rank_issues` | Change issue ranking |
464
+
465
+ </details>
466
+
467
+ <details>
468
+ <summary><strong>🔗 Issue Relationships (9 tools)</strong></summary>
469
+
470
+ | Tool | Description |
471
+ |------|-------------|
472
+ | `jira_get_issue_links` | Get linked issues |
473
+ | `jira_create_issue_link` | Link two issues together |
474
+ | `jira_get_link_types` | Get available link types |
475
+ | `jira_get_watchers` | Get issue watchers |
476
+ | `jira_add_watcher` | Add a watcher to an issue |
477
+ | `jira_remove_watcher` | Remove a watcher |
478
+ | `jira_get_votes` | Get issue vote count |
479
+ | `jira_add_vote` | Vote for an issue |
480
+ | `jira_remove_vote` | Remove your vote |
481
+
482
+ </details>
483
+
484
+ <details>
485
+ <summary><strong> Epic Management (4 tools)</strong></summary>
486
+
487
+ | Tool | Description |
488
+ |------|-------------|
489
+ | `jira_get_epics` | Get epics for a board |
490
+ | `jira_get_epic_issues` | Get issues belonging to an epic |
491
+ | `jira_move_issues_to_epic` | Move issues to an epic |
492
+ | `jira_remove_issues_from_epic` | Remove issues from an epic |
493
+
494
+ </details>
495
+
496
+ <details>
497
+ <summary><strong>🗂️ Field Metadata (3 tools)</strong></summary>
498
+
499
+ | Tool | Description |
500
+ |------|-------------|
501
+ | `jira_get_fields` | Get all available fields (including custom) |
502
+ | `jira_get_create_metadata` | Get metadata for creating issues |
503
+ | `jira_get_edit_metadata` | Get metadata for editing issues |
504
+
505
+ </details>
506
+
507
+ <details>
508
+ <summary><strong>🗄️ Filters (6 tools)</strong></summary>
509
+
510
+ | Tool | Description |
511
+ |------|-------------|
512
+ | `jira_get_filters` | Search saved filters |
513
+ | `jira_get_filter` | Get filter details |
514
+ | `jira_create_filter` | Create a new saved filter |
515
+ | `jira_update_filter` | Update an existing filter |
516
+ | `jira_get_my_filters` | Get filters owned by you |
517
+ | `jira_get_favourite_filters` | Get favourite filters |
518
+
519
+ </details>
520
+
521
+ <details>
522
+ <summary><strong>⚡ Bulk Operations (4 tools)</strong></summary>
523
+
524
+ | Tool | Description |
525
+ |------|-------------|
526
+ | `jira_bulk_edit_issues` | Edit multiple issues at once (labels, assignee, priority, etc.) |
527
+ | `jira_bulk_watch_issues` | Add watchers to multiple issues |
528
+ | `jira_bulk_unwatch_issues` | Remove watchers from multiple issues |
529
+ | `jira_get_bulk_operation_progress` | Track async bulk operation progress |
530
+
531
+ </details>
532
+
533
+ <details>
534
+ <summary><strong>📊 Dashboard Management (5 tools)</strong></summary>
535
+
536
+ | Tool | Description |
537
+ |------|-------------|
538
+ | `jira_get_dashboards` | Get dashboards (filter by favourite/owned) |
539
+ | `jira_search_dashboards` | Search dashboards by name, owner, etc. |
540
+ | `jira_get_dashboard` | Get dashboard details by ID |
541
+ | `jira_get_dashboard_gadgets` | Get all gadgets on a dashboard |
542
+ | `jira_add_dashboard_gadget` | Add a gadget to a dashboard |
543
+
544
+ </details>
545
+
546
+ <details>
547
+ <summary><strong>📎 Enhanced Attachments (4 tools)</strong></summary>
548
+
549
+ | Tool | Description |
550
+ |------|-------------|
551
+ | `jira_get_attachments` | Get issue attachments |
552
+ | `jira_upload_attachment` | Upload a file to an issue |
553
+ | `jira_get_attachment_metadata` | Get attachment metadata by ID |
554
+ | `jira_get_attachment_content` | Get attachment download URL |
555
+
556
+ </details>
557
+
558
+ <details>
559
+ <summary><strong>🏷️ Labels Management (2 tools)</strong></summary>
560
+
561
+ | Tool | Description |
562
+ |------|-------------|
563
+ | `jira_get_all_labels` | Get all labels in the Jira instance |
564
+ | `jira_add_labels` | Add, set, or remove labels on an issue |
565
+
566
+ </details>
567
+
568
+ <details>
569
+ <summary><strong>🔎 JQL Tools (3 tools)</strong></summary>
570
+
571
+ | Tool | Description |
572
+ |------|-------------|
573
+ | `jira_autocomplete_jql` | Get autocomplete suggestions for JQL fields |
574
+ | `jira_validate_jql` | Validate JQL queries for syntax errors |
575
+ | `jira_parse_jql` | Parse JQL into abstract syntax tree |
576
+
577
+ </details>
578
+
579
+ <details>
580
+ <summary><strong>⏱️ Time Tracking Reports (4 tools)</strong></summary>
581
+
582
+ | Tool | Description |
583
+ |------|-------------|
584
+ | `jira_get_updated_worklog_ids` | Get worklog IDs created/updated since a date |
585
+ | `jira_get_worklogs_by_ids` | Get full worklog details by IDs (batch up to 1000) |
586
+ | `jira_get_user_worklogs` | Get all worklogs for a user in a date range with summary |
587
+ | `jira_get_deleted_worklog_ids` | Get IDs of deleted worklogs for audit purposes |
588
+
589
+ </details>
590
+
591
+ ### 🛡️ Phase 14: Code Quality & Security
592
+
593
+ This release underwent a comprehensive audit to ensure best practices and security:
594
+
595
+ | Category | Status | Details |
596
+ |----------|:------:|---------|
597
+ | **API Version** | ✅ | All 73 tools use Jira REST API v3 (latest) |
598
+ | **Agile API** | ✅ | Sprint/Board tools use Jira Agile API v1.0 |
599
+ | **Deprecated APIs** | ✅ | All deprecated endpoints migrated to modern alternatives |
600
+ | **Security Vulnerabilities** | ✅ | 0 vulnerabilities (axios & qs patched) |
601
+ | **OAuth 2.0 Support** | ✅ | Full OAuth 2.0 (3LO) with auto-refresh |
602
+ | **Credential Storage** | ✅ | OS-level encryption via Keytar |
603
+ | **Input Validation** | ✅ | Zod v4 schema validation on all parameters |
604
+ | **URL Encoding** | ✅ | All dynamic path parameters properly encoded |
605
+ | **Error Handling** | ✅ | Consistent error handling across all endpoints |
606
+
607
+ ## 💡 Usage Examples
608
+
609
+ Once configured, interact with Jira through natural conversation:
610
+
611
+ ### Issue Management
612
+
613
+ ```
614
+ 👤 "What's the status of PROJ-123?"
615
+ 🤖 Fetches and displays issue details, status, and assignee
616
+
617
+ 👤 "Create a bug in PROJ for 'Login button not working'"
618
+ 🤖 Creates a new bug issue and returns the issue key
619
+
620
+ 👤 "Assign PROJ-456 to john@example.com"
621
+ 🤖 Assigns the issue to the specified user
622
+
623
+ 👤 "Move PROJ-789 to 'In Progress'"
624
+ 🤖 Transitions the issue to the new status
625
+ ```
626
+
627
+ ### Sprint & Agile
628
+
629
+ ```
630
+ 👤 "Show me the active sprint for board 123"
631
+ 🤖 Displays current sprint details with dates and goal
632
+
633
+ 👤 "Move PROJ-123 and PROJ-124 to sprint 456"
634
+ 🤖 Moves the issues to the specified sprint
635
+
636
+ 👤 "What's in the backlog for the PROJ board?"
637
+ 🤖 Lists all backlog issues with priorities
638
+ ```
639
+
640
+ ### Time Tracking
641
+
642
+ ```
643
+ 👤 "Log 2 hours on PROJ-456 for code review"
644
+ 🤖 Creates work log entry with description
645
+
646
+ 👤 "How much time has been logged on PROJ-789?"
647
+ 🤖 Retrieves and summarises work logs
648
+ ```
649
+
650
+ ### Collaboration
651
+
652
+ ```
653
+ 👤 "Link PROJ-123 as blocking PROJ-456"
654
+ 🤖 Creates a "blocks" relationship between issues
655
+
656
+ 👤 "Add me as a watcher on PROJ-789"
657
+ 🤖 Adds you to the issue's watch list
658
+
659
+ 👤 "Show all issues in epic PROJ-100"
660
+ 🤖 Lists all child issues of the epic
661
+ ```
662
+
663
+ ## 🔧 Troubleshooting
664
+
665
+ <details>
666
+ <summary><strong>❌ "MISSING_AUTH" Error</strong></summary>
667
+
668
+ Ensure your environment variables are correctly set. Verify with `jira_auth_status`.
669
+
670
+ **Checklist:**
671
+ - ✅ `JIRA_BASE_URL` includes `https://` and is your full Jira domain
672
+ - ✅ `JIRA_EMAIL` matches your Atlassian account email
673
+ - ✅ `JIRA_API_TOKEN` is a valid, non-expired token
674
+
675
+ </details>
676
+
677
+ <details>
678
+ <summary><strong>❌ "401 Unauthorised" Error</strong></summary>
679
+
680
+ Your credentials are invalid or expired.
681
+
682
+ **For Basic Auth:**
683
+ - Verify your API token at [Atlassian API Tokens](https://id.atlassian.com/manage-profile/security/api-tokens)
684
+ - Ensure the token hasn't been revoked
685
+
686
+ **For OAuth:**
687
+ - Try refreshing the token with `jira_oauth_refresh`
688
+ - Re-authenticate if the refresh token has expired
689
+
690
+ </details>
691
+
692
+ <details>
693
+ <summary><strong>❌ "403 Forbidden" Error</strong></summary>
694
+
695
+ You don't have permission to access the requested resource.
696
+
697
+ **Solutions:**
698
+ - Check your Jira permissions for the project
699
+ - Contact your Jira administrator
700
+ - Verify your OAuth scopes include required permissions
701
+
702
+ </details>
703
+
704
+ <details>
705
+ <summary><strong>❌ "404 Not Found" Error</strong></summary>
706
+
707
+ The issue or project doesn't exist, or you don't have access to view it.
708
+
709
+ **Solutions:**
710
+ - Verify the issue key is correct (e.g., `PROJ-123`)
711
+ - Check if you have access to the project
712
+ - Ensure the issue hasn't been deleted or moved
713
+
714
+ </details>
715
+
716
+ ## 📦 Package Information
717
+
718
+ | Attribute | Value |
719
+ |-----------|-------|
720
+ | Package name | [`mcp-jira-cloud`](https://www.npmjs.com/package/mcp-jira-cloud) |
721
+ | Version | **2.2.0** |
722
+ | License | [MIT](LICENSE) |
723
+ | Node.js | ≥18.0.0 |
724
+ | TypeScript | ≥5.0.0 |
725
+ | Module | ES Modules |
726
+ | Tools | **78** |
727
+
728
+ ### Dependencies
729
+
730
+ | Package | Purpose |
731
+ |---------|---------|
732
+ | [`@modelcontextprotocol/sdk`](https://www.npmjs.com/package/@modelcontextprotocol/sdk) | MCP protocol implementation |
733
+ | [`axios`](https://www.npmjs.com/package/axios) | HTTP client for Jira API |
734
+ | [`keytar`](https://www.npmjs.com/package/keytar) | Secure credential storage |
735
+ | [`zod`](https://www.npmjs.com/package/zod) | Schema validation |
736
+
737
+ ## 🆕 What's New in v2.0.0
738
+
739
+ <details>
740
+ <summary><strong>Click to see full changelog</strong></summary>
741
+
742
+ ### Added
743
+ - **Issue CRUD** - Create, update, delete issues with full field support
744
+ - **Workflow Transitions** - Move issues through workflow states
745
+ - **Agile/Scrum** - Complete sprint and board management (15 tools)
746
+ - **Issue Linking** - Blocks, relates, duplicates relationships
747
+ - **Watchers & Voting** - Collaboration features
748
+ - **Epic Management** - Organise issues under epics
749
+ - **Filters** - Create and manage saved JQL filters
750
+ - **Metadata** - Access field configurations and create metadata
751
+ - **Bulk Operations** - Edit, watch, unwatch multiple issues at once
752
+ - **Dashboard Management** - View and manage Jira dashboards and gadgets
753
+ - **Enhanced Attachments** - Upload attachments, get metadata and content
754
+ - **Labels Management** - Get all labels, bulk add/remove/set labels
755
+ - **JQL Tools** - Autocomplete, validate, and parse JQL queries
756
+ - **Time Tracking Reports** - Get user worklogs for any date range with summaries
757
+
758
+ ### Changed
759
+ - Total tools increased from 18 to 78
760
+ - Improved TypeScript strict mode compliance
761
+ - Enhanced error handling and validation
762
+
763
+ </details>
764
+
765
+ ## 🔒 Security
766
+
767
+ - Credentials are stored securely via system keychain (Keytar)
768
+ - OAuth tokens auto-refresh before expiration
769
+ - No credentials are logged or exposed in error messages
770
+ - See [SECURITY.md](SECURITY.md) for our security policy
771
+
772
+ ## 🤝 Contributing
773
+
774
+ Contributions are welcome! Please see [CONTRIBUTING.md](CONTRIBUTING.md) for guidelines.
775
+
776
+ 1. Fork the repository
777
+ 2. Create a feature branch (`git checkout -b feature/amazing-feature`)
778
+ 3. Commit your changes (`git commit -m 'Add amazing feature'`)
779
+ 4. Push to the branch (`git push origin feature/amazing-feature`)
780
+ 5. Open a Pull Request
781
+
782
+ ## 📄 Changelog
783
+
784
+ See [CHANGELOG.md](CHANGELOG.md) for a list of changes in each version.
785
+
786
+ ## 📜 License
787
+
788
+ This project is licensed under the **MIT License** — see the [LICENSE](LICENSE) file for details.
789
+
790
+ ## 🔗 Links
791
+
792
+ | Resource | Link |
793
+ |----------|------|
794
+ | GitHub | [github.com/tezaswi7222/jira-mcp](https://github.com/tezaswi7222/jira-mcp) |
795
+ | npm | [npmjs.com/package/mcp-jira-cloud](https://www.npmjs.com/package/mcp-jira-cloud) |
796
+ | Issues | [Report a bug](https://github.com/tezaswi7222/jira-mcp/issues) |
797
+ | MCP Protocol | [modelcontextprotocol.io](https://modelcontextprotocol.io/) |
798
+ | Jira API | [Jira REST API v3](https://developer.atlassian.com/cloud/jira/platform/rest/v3/intro/) |
799
+
800
+ ---
801
+
802
+ <p align="center">
803
+ Made with ❤️ by <a href="https://github.com/tezaswi7222">Tezaswi Raj (github: tezaswi7222)</a>
804
+ </p>
805
+
806
+ <p align="center">
807
+ <a href="https://github.com/sponsors/tezaswi7222">
808
+ <img src="https://img.shields.io/badge/Sponsor-❤️-ea4aaa?style=for-the-badge" alt="Sponsor">
809
+ </a>
810
+ </p>