JIRA MCP Skill
This skill provides comprehensive JIRA project management capabilities through direct API calls.
Prerequisites
- Create
.env file in project root:
JIRA_BASE_URL=https://your-jira-url/jira
JIRA_COOKIES=JSESSIONID=xxx; atlassian.xsrf.token=xxx_lin; seraph.rememberme.cookie=xxx
- Install dependencies:
npm install axios dotenv
Cookie Authentication Guide
How to Get Valid Cookies
- Open
https://your-jira-url/jira in browser and login
- Check "Remember Me" — this is critical for
seraph.rememberme.cookie
- Press F12 → Application → Cookies → select JIRA domain
- Copy the following cookies in
key=value format separated by ;:
| Cookie Name |
Required |
Notes |
JSESSIONID |
Yes |
Path must be /jira |
atlassian.xsrf.token |
Yes |
Must end with _lin (not _lout) |
seraph.rememberme.cookie |
Yes |
Only present when "Remember Me" is checked |
ngx_jira |
Recommended |
Load balancer routing |
Cookie Format Example
JSESSIONID=A2804783A2950FC80743E2077B6E1011; atlassian.xsrf.token=BW0V-G7S3-B591-HO9N_xxx_lin; seraph.rememberme.cookie=2257687%3A930cc1c202f26ff1e7f3f3de14b4c3fa9ea1d996; ngx_jira=192.168.142.201:8080
Cookie Validation
The skill automatically validates cookie format before API calls:
atlassian.xsrf.token ending with _lout → 已登出，需要重新登录atlassian.xsrf.token ending with _lin → 已登录，正常- Missing
seraph.rememberme.cookie → 需要在登录时勾选"记住我"
Available Operations
Authentication Functions
| Function |
Description |
checkAuth() |
Verify authentication status, returns user info |
getAuthStatus() |
Get current auth configuration (no API call) |
validateCookieFormat(cookies) |
Validate cookie format and completeness |
ensureAuthenticated() |
Pre-check before API calls |
Core Functions
| Function |
Description |
searchIssues(jql, fields, maxResults) |
Search issues with JQL |
getIssue(issueKey) |
Get single issue details |
getBoardIssues(boardId, maxResults) |
Get all issues on a board |
getProjectBoards(projectKey) |
Get boards for a project |
getProjects() |
List all projects |
getProjectVersions(projectKey) |
Get versions for a project |
getCustomFieldOptions(fieldId) |
Get options for a custom field |
createIssue(issueData) |
Create new issue |
createImproveTask(summary, options) |
Create IMPROVE1 project task with required fields |
createSubtask(parentKey, summary, options) |
Create subtask |
Convenience Functions
| Function |
Description |
getTaskProgress(taskKeys) |
Get task completion progress |
getBugStatus(boardId) |
Get bug status report |
getOpenTasksByAssignee(taskKeys) |
Group open tasks by assignee |
Usage Examples
Check Authentication
const jira = require('./jira-client');
const auth = await jira.checkAuth();
if (!auth.valid) {
console.log('Auth failed:', auth.error);
console.log('Hint:', auth.hint);
}
const cookieStatus = jira.validateCookieFormat(process.env.JIRA_COOKIES);
if (!cookieStatus.valid) {
console.log('Cookie issues:', cookieStatus.issues);
}
Task Progress Tracking
const progress = await jira.getTaskProgress(['ISID-7010', 'ISID-7011']);
console.log(`Progress: ${progress.progress}%`);
Bug Status Report
const status = await jira.getBugStatus(2162);
console.log(`BUG Progress: ${status.progress}%`);
console.log('High Priority:', status.highPriority);
Create Task
await jira.createIssue({
project: { key: 'ISID' },
summary: 'New Task',
issuetype: { name: 'Task' },
assignee: { name: 'username' }
});
Create IMPROVE1 Task (结项门禁核查)
const result = await jira.createImproveTask('【结项门禁核查】PVM-RSAS-V6.0R04F04SP11', {
assignee: 'jibo', // 经办人
reporter: 'wangqiang4', // 报告人
projectType: '公共支持',
fixVersion: '2026年年度过程改进'
});
console.log('Task created:', result.key);
Custom Fields Reference
| Field Name |
Field ID |
Description |
| Task Type |
customfield_10315 |
Development/Test/Design |
| Project Type |
customfield_11443 |
Maintenance(SP)/Feature |
| Start Date |
customfield_10302 |
Date format |
| End Date |
customfield_10303 |
Date format |
| Estimate |
customfield_10105 |
Time estimate (e.g., 5d) |
Troubleshooting
Common Cookie Errors
| Symptom |
Cause |
Solution |
| 401 Unauthorized |
Cookie expired |
Re-login and update cookies |
401 + _lout token |
Logged out state |
Re-login, ensure token ends with _lin |
| 302 Redirect |
SSO redirect |
Cookie incomplete or invalid |
Missing seraph.rememberme.cookie |
Didn't check "Remember Me" |
Re-login with "Remember Me" checked |
| dotenv path error |
.env not found |
Skill auto-searches multiple paths |
Common API Errors
| Error |
Cause |
Solution |
| 401 |
Cookie expired or invalid |
Run checkAuth() to diagnose |
| 302 |
SSO redirect |
Check cookie format |
| 404 |
Invalid ID |
Verify the ID exists |
| 400 JQL error |
Invalid JQL syntax |
Check JQL query syntax |
| 400 field error |
Invalid custom field value |
Verify field ID and allowed values |
Auto .env Loading
The skill automatically searches for .env in these paths (in order):
process.cwd()/.env../../.env (from skill directory)../.env./.env
Authentication
Method 1: Cookies (Recommended for SSO)
- Login to JIRA in browser (check "Remember Me")
- Press F12 → Application → Cookies
- Copy required cookies (see Cookie Authentication Guide above)
Method 2: Bearer Token
- Login to JIRA
- Find request with Authorization header in dev tools
- Copy the full Bearer token
tigerjibo