Mode: Cognitive/Prompt-Driven - No standalone utility script; use via agent context.
Required:
- JIRA_URL - Base URL of your Jira instance (e.g., https://yourcompany.atlassian.net)
- JIRA_API_TOKEN - API token for authentication (generate at Jira Account Settings -> Security -> API Tokens)
- JIRA_USER_EMAIL - Email address associated with the API token
Optional:
- JIRA_DEFAULT_PROJECT - Default project key for operations (e.g., PROJ)
- JIRA_API_VERSION - API version (default: 3)
Issues
| Tool |
Description |
Confirmation Required |
| search |
Search issues using JQL |
No |
| get-issue |
Get detailed issue information |
No |
| create-issue |
Create a new issue |
Yes |
| update-issue |
Update existing issue fields |
Yes |
| transition |
Change issue status/workflow state |
Yes |
Projects
| Tool |
Description |
| list-projects |
List all accessible projects |
| project-info |
Get detailed project information |
Sprints
| Tool |
Description |
| active-sprint |
Get currently active sprint for a board |
| sprint-issues |
List all issues in a specific sprint |
Comments
| Tool |
Description |
| get-comments |
Retrieve all comments on an issue |
| add-comment |
Add a comment to an issue |
Common Workflows
Issue Creation: List projects -> Get project info -> Create issue -> Add comment
Sprint Management: Get active sprint -> List sprint issues -> Update issue status -> Add comments
Issue Search: Use JQL for targeted searches -> Retrieve issue details -> Update issues
Primary Agent: planner
- Use Case: Project backlog management, sprint planning, requirement tracking
- Common Operations: Create issues, update priorities, manage sprints
Secondary Agent: developer
- Use Case: Issue tracking during development, status updates
- Common Operations: Search assigned issues, transition issues, add comments
Common Error Scenarios
- Authentication Errors: Missing or invalid API token, expired credentials, insufficient permissions
- Rate Limiting: Too many API requests in short period, implement exponential backoff
- Invalid Inputs: Non-existent project keys, invalid issue types, invalid transition IDs
- Network Errors: Connection timeouts, unreachable Jira instance
- Use JQL Efficiently: Craft precise JQL queries to reduce result sets and API calls
- Cache Metadata: Store project keys, issue types, and transitions locally
- Verify Before Create: Always verify project and issue type before creating issues
- Use Transitions: Respect workflow states when changing issue status
- Batch Operations: Group related API calls when possible
- Handle Errors Gracefully: Provide clear error messages and recovery suggestions
- Respect Rate Limits: Implement backoff strategies for high-volume operations
Context Optimization
- Lazy Loading: Only load issue details when explicitly requested
- Field Selection: Request only necessary fields from Jira API
- Caching: Store frequently accessed metadata (projects, issue types)
- Streaming: Not supported - all responses are complete payloads
- Pagination: Automatically handle large result sets
Context Savings: 90%+ compared to loading full Jira MCP server
Jira REST API Endpoints Used
- /rest/api/3/search - JQL search
- /rest/api/3/issue/{issueKey} - Get/update issue
- /rest/api/3/issue - Create issue
- /rest/api/3/issue/{issueKey}/transitions - Transition issue
- /rest/api/3/project - List projects
- /rest/api/3/project/{projectKey} - Get project details
- /rest/agile/1.0/board/{boardId}/sprint - Get sprints
- /rest/agile/1.0/sprint/{sprintId}/issue - Get sprint issues
- /rest/api/3/issue/{issueKey}/comment - Get/add comments
See https://developer.atlassian.com/cloud/jira/platform/rest/v3/ for full reference.
Iron Laws
- ALWAYS verify the project key exists before creating an issue — Jira silently ignores invalid project keys in some API versions, creating orphaned issues or returning cryptic errors.
- NEVER use
PUT /issue to change status — Jira status changes must go through valid workflow transitions via POST /issue/{key}/transitions; direct field updates bypass workflow validators and automation rules.
- ALWAYS use JQL for issue searches rather than fetching all issues and filtering client-side — returning all issues wastes quota and causes timeouts on projects with thousands of tickets.
- NEVER create duplicate issues without first searching for existing ones — duplicate tickets fragment tracking, confuse assignees, and produce misleading velocity metrics.
- ALWAYS include
summary, issuetype, and project fields when creating an issue — these three fields are the minimum required by Jira Cloud REST API v3; missing any produces a 400 error.
Anti-Patterns
| Anti-Pattern |
Why It Fails |
Correct Approach |
| Updating status via field PUT |
Bypasses workflow guards; invalid state transitions succeed silently; automation rules don't fire |
Use POST /issue/{key}/transitions with the correct transition ID |
| Fetching all issues and filtering locally |
Times out on large projects; wastes API quota; slow for paginated results |
Always use JQL with specific project/sprint/status filters |
| Creating issues without duplication check |
Splits work tracking; team sees multiple tickets for same task |
Search with JQL (project = X AND summary ~ "keyword") before creating |
Hardcoding field IDs (e.g., customfield_10016) |
Field IDs differ between Jira instances and cloud/server; breaks across projects |
Discover field IDs dynamically via /rest/api/3/field endpoint |
| No error handling for rate limits (429) |
Jira Cloud rate limits at ~300 requests/minute; unhandled 429 crashes automation |
Implement exponential backoff; check Retry-After header on 429 responses |
Memory Protocol (MANDATORY)
Before starting:
Read .claude/context/memory/learnings.md
After completing:
- New pattern -> .claude/context/memory/learnings.md
- Issue found -> .claude/context/memory/issues.md
- Decision made -> .claude/context/memory/decisions.md
ASSUME INTERRUPTION: If it is not in memory, it did not happen.
1---2name: jira-pm3description: Jira project management and issue tracking integration4---56**Mode: Cognitive/Prompt-Driven** - No standalone utility script; use via agent context.78<identity>9Jira PM (Project Management) - Provides integration with Atlassian Jira for issue tracking, project management, and workflow automation. Enables 90%+ context savings over direct MCP integration.10</identity>1112<capabilities>13- Issue management: search, create, update, transition14- Project discovery and metadata retrieval15- Sprint management and issue tracking16- Comment management on issues17- JQL-based advanced queries18</capabilities>1920<requirements>21## Environment Variables2223Required:2425- JIRA_URL - Base URL of your Jira instance (e.g., <https://yourcompany.atlassian.net>)26- JIRA_API_TOKEN - API token for authentication (generate at Jira Account Settings -> Security -> API Tokens)27- JIRA_USER_EMAIL - Email address associated with the API token2829Optional:3031- JIRA_DEFAULT_PROJECT - Default project key for operations (e.g., PROJ)32- JIRA_API_VERSION - API version (default: 3)33 </requirements>3435<instructions>36<execution_process>371. Authentication: All requests use Basic Auth with JIRA_USER_EMAIL and JIRA_API_TOKEN382. Progressive Disclosure: Load only necessary issue fields to minimize API calls393. Validation: Verify project keys and issue keys before operations404. Error Handling: Gracefully handle rate limits, authentication errors, and invalid inputs41</execution_process>4243<tool_categories>4445## Issues4647| Tool | Description | Confirmation Required |48| ------------ | ---------------------------------- | --------------------- |49| search | Search issues using JQL | No |50| get-issue | Get detailed issue information | No |51| create-issue | Create a new issue | Yes |52| update-issue | Update existing issue fields | Yes |53| transition | Change issue status/workflow state | Yes |5455## Projects5657| Tool | Description |58| ------------- | -------------------------------- |59| list-projects | List all accessible projects |60| project-info | Get detailed project information |6162## Sprints6364| Tool | Description |65| ------------- | --------------------------------------- |66| active-sprint | Get currently active sprint for a board |67| sprint-issues | List all issues in a specific sprint |6869## Comments7071| Tool | Description |72| ------------ | --------------------------------- |73| get-comments | Retrieve all comments on an issue |74| add-comment | Add a comment to an issue |7576</tool_categories>7778<usage_patterns>7980## Common Workflows8182**Issue Creation**: List projects -> Get project info -> Create issue -> Add comment8384**Sprint Management**: Get active sprint -> List sprint issues -> Update issue status -> Add comments8586**Issue Search**: Use JQL for targeted searches -> Retrieve issue details -> Update issues8788</usage_patterns>8990<agent_integration>9192## Primary Agent: planner9394- Use Case: Project backlog management, sprint planning, requirement tracking95- Common Operations: Create issues, update priorities, manage sprints9697## Secondary Agent: developer9899- Use Case: Issue tracking during development, status updates100- Common Operations: Search assigned issues, transition issues, add comments101102</agent_integration>103104<error_handling>105106## Common Error Scenarios107108- Authentication Errors: Missing or invalid API token, expired credentials, insufficient permissions109- Rate Limiting: Too many API requests in short period, implement exponential backoff110- Invalid Inputs: Non-existent project keys, invalid issue types, invalid transition IDs111- Network Errors: Connection timeouts, unreachable Jira instance112113</error_handling>114115<best_practices>1161171. Use JQL Efficiently: Craft precise JQL queries to reduce result sets and API calls1182. Cache Metadata: Store project keys, issue types, and transitions locally1193. Verify Before Create: Always verify project and issue type before creating issues1204. Use Transitions: Respect workflow states when changing issue status1215. Batch Operations: Group related API calls when possible1226. Handle Errors Gracefully: Provide clear error messages and recovery suggestions1237. Respect Rate Limits: Implement backoff strategies for high-volume operations124125</best_practices>126</instructions>127128<progressive_disclosure>129130## Context Optimization1311321. Lazy Loading: Only load issue details when explicitly requested1332. Field Selection: Request only necessary fields from Jira API1343. Caching: Store frequently accessed metadata (projects, issue types)1354. Streaming: Not supported - all responses are complete payloads1365. Pagination: Automatically handle large result sets137138Context Savings: 90%+ compared to loading full Jira MCP server139</progressive_disclosure>140141<api_reference>142143## Jira REST API Endpoints Used144145- /rest/api/3/search - JQL search146- /rest/api/3/issue/{issueKey} - Get/update issue147- /rest/api/3/issue - Create issue148- /rest/api/3/issue/{issueKey}/transitions - Transition issue149- /rest/api/3/project - List projects150- /rest/api/3/project/{projectKey} - Get project details151- /rest/agile/1.0/board/{boardId}/sprint - Get sprints152- /rest/agile/1.0/sprint/{sprintId}/issue - Get sprint issues153- /rest/api/3/issue/{issueKey}/comment - Get/add comments154155See <https://developer.atlassian.com/cloud/jira/platform/rest/v3/> for full reference.156</api_reference>157158## Iron Laws1591601. **ALWAYS** verify the project key exists before creating an issue — Jira silently ignores invalid project keys in some API versions, creating orphaned issues or returning cryptic errors.1612. **NEVER** use `PUT /issue` to change status — Jira status changes must go through valid workflow transitions via `POST /issue/{key}/transitions`; direct field updates bypass workflow validators and automation rules.1623. **ALWAYS** use JQL for issue searches rather than fetching all issues and filtering client-side — returning all issues wastes quota and causes timeouts on projects with thousands of tickets.1634. **NEVER** create duplicate issues without first searching for existing ones — duplicate tickets fragment tracking, confuse assignees, and produce misleading velocity metrics.1645. **ALWAYS** include `summary`, `issuetype`, and `project` fields when creating an issue — these three fields are the minimum required by Jira Cloud REST API v3; missing any produces a 400 error.165166## Anti-Patterns167168| Anti-Pattern | Why It Fails | Correct Approach |169| ------------------------------------------------ | ------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------- |170| Updating status via field PUT | Bypasses workflow guards; invalid state transitions succeed silently; automation rules don't fire | Use `POST /issue/{key}/transitions` with the correct transition ID |171| Fetching all issues and filtering locally | Times out on large projects; wastes API quota; slow for paginated results | Always use JQL with specific project/sprint/status filters |172| Creating issues without duplication check | Splits work tracking; team sees multiple tickets for same task | Search with JQL (`project = X AND summary ~ "keyword"`) before creating |173| Hardcoding field IDs (e.g., `customfield_10016`) | Field IDs differ between Jira instances and cloud/server; breaks across projects | Discover field IDs dynamically via `/rest/api/3/field` endpoint |174| No error handling for rate limits (429) | Jira Cloud rate limits at ~300 requests/minute; unhandled 429 crashes automation | Implement exponential backoff; check `Retry-After` header on 429 responses |175176## Memory Protocol (MANDATORY)177178**Before starting:**179Read .claude/context/memory/learnings.md180181**After completing:**182183- New pattern -> .claude/context/memory/learnings.md184- Issue found -> .claude/context/memory/issues.md185- Decision made -> .claude/context/memory/decisions.md186187> ASSUME INTERRUPTION: If it is not in memory, it did not happen.
oimiragieo