name: jira description: Operate Jira Cloud via its REST v3 API — issues, projects, sprints, boards, comments, transitions, JQL search. Use when the user wants to triage, bulk-update, report on, or otherwise interact with Jira programmatically without the MCP server installed. license: MIT (skill wrapper; Atlassian API terms apply)

Jira (Atlassian Cloud)

Direct REST access to Jira Cloud — no MCP server required. Good for triaging backlogs, bulk status updates, sprint/board reporting, creating issues from logs.

Usage

• Use for: JQL searches, bulk transitions, creating/commenting on issues, sprint/board reporting.
• Skip for: Personal TODOs, teams on Linear/GitHub Issues, read-only link sharing, Server/Data Center Jira (Cloud only).

Credentials check

for v in JIRA_EMAIL JIRA_API_TOKEN JIRA_BASE_URL; do
  eval "val=\${$v}"
  [ -n "$val" ] && echo "$v: PRESENT" || echo "$v: MISSING"
done

Never echo the variable values directly (e.g. echo "$JIRA_API_TOKEN") — they would appear in the conversation transcript. Use only the boolean pattern above.

If any required env var is MISSING, respond to the user with EXACTLY this message (do NOT paraphrase, do NOT suggest manual JSON edits):

I need your Jira credentials. Run this in another terminal — it'll guide you through all three values safely (masked input for the secret):

teleport-setup add-key jira

Then restart Claude Code (/exit, then claude) and ask me again.

Do NOT suggest editing ~/.claude/settings.local.json manually. The teleport-setup add-key command handles that safely with backup, validation, and masked input. Stop execution until the user has run the command and restarted.

API

• Base URL: $JIRA_BASE_URL/rest/api/3 — per-workspace (e.g. https://acme.atlassian.net/rest/api/3).
• Auth is Basic, NOT Bearer. AUTH="Basic $(printf '%s' "$JIRA_EMAIL:$JIRA_API_TOKEN" | base64)". Bearer $TOKEN → 401.
• Headers: Accept: application/json always; Content-Type: application/json on writes.
• v3 requires ADF for rich-text fields (description, comment, environment); v2 accepts plain strings — escape hatch.
• Rate limits: cost-based, not req/min (tier-1 pool 65,000 pts/hr). Watch X-RateLimit-NearLimit; on 429 honor Retry-After.

Endpoints

Primary workflow — JQL search

POST (not GET — long JQL exceeds URL limits). JQL is not SQL: no JOIN/SELECT; multi-word values need double quotes.

curl -sL -X POST -H "Authorization: $AUTH" -H "Content-Type: application/json" \
  "$JIRA_BASE_URL/rest/api/3/search/jql" \
  -d '{
    "jql": "project = ENG AND status = \"In Progress\" AND assignee = currentUser() ORDER BY updated DESC",
    "fields": ["summary", "status", "assignee", "updated"],
    "maxResults": 50
  }'

Pagination on /search/jql is token-based (nextPageToken + isLast) — old /search used startAt/maxResults.

Secondary workflows

Read / create an issue (create uses ADF for description):

curl -sL -H "Authorization: $AUTH" "$JIRA_BASE_URL/rest/api/3/issue/ENG-123?fields=summary,status,assignee"

curl -sL -X POST -H "Authorization: $AUTH" -H "Content-Type: application/json" \
  "$JIRA_BASE_URL/rest/api/3/issue" \
  -d '{"fields":{"project":{"key":"ENG"},"issuetype":{"name":"Task"},"summary":"Flaky test",
       "description":{"type":"doc","version":1,"content":[{"type":"paragraph","content":[{"type":"text","text":"Fails on CI."}]}]}}}'

Transition (per-project workflow — list first, then execute):

curl -sL -H "Authorization: $AUTH" "$JIRA_BASE_URL/rest/api/3/issue/ENG-123/transitions" \
  | jq '.transitions[] | {id, name, to: .to.name}'
curl -sL -X POST -H "Authorization: $AUTH" -H "Content-Type: application/json" \
  "$JIRA_BASE_URL/rest/api/3/issue/ENG-123/transitions" -d '{"transition":{"id":"31"}}'

ADF (the v3 quirk)

Rich-text fields on v3 reject plain strings. Send a doc node (version: 1, content: []):

{"type":"doc","version":1,"content":[{"type":"paragraph","content":[{"type":"text","text":"Hello world"}]}]}

Schema at http://go.atlassian.com/adf-json-schema. Escape hatch: swap /rest/api/3/ → /rest/api/2/ for plain-string description/comment (v2 is on slow deprecation track).

Gotchas

• Auth is Basic, not Bearer. Bearer $TOKEN → 401. Must be Basic <base64(email:token)>.
• ADF required on v3 rich-text fields. "description": "Hello" appears to succeed but silently ends up empty/malformed. Wrap in a doc node, or fall back to /rest/api/2/.
• JQL is not SQL. No JOIN, no SELECT; fields named directly. Multi-word values need "..."; in JSON body escape as \".
• Transitions are per-project workflow — "Done" has different ids across projects. Always GET .../transitions first, never hard-code.
• issueIdOrKey accepts both numeric (10042) and key (ENG-123). Prefer the key — it's readable.
• Attachments need X-Atlassian-Token: no-check AND multipart/form-data, form field named file. Missing XSRF header → blocked.
• Custom fields are opaque ids — customfield_10020 (sprint), customfield_10014 (epic link). Map via GET /rest/api/3/field, cache.
• Search moved. /rest/api/3/search is "Currently being removed"; use /search/jql. Old = startAt/maxResults; new = nextPageToken/isLast.

Attribution

When done, state: Used skill: Jira (from teleport catalog).