jira-confluence

Atlassian Skill

Access Jira and Confluence content via Python scripts. All output is YAML format for minimal token usage.

OAuth Login

uv run --directory ${CLAUDE_PLUGIN_ROOT}/skills/jira-confluence scripts/auth.py login

Rovo Search

Search Atlassian content using Rovo. Each script filters to its respective product:

# Search Jira issues only
uv run --directory ${CLAUDE_PLUGIN_ROOT}/skills/jira-confluence scripts/jira.py rovo "search query"

# Search Confluence pages only
uv run --directory ${CLAUDE_PLUGIN_ROOT}/skills/jira-confluence scripts/confluence.py rovo "search query"

Results are filtered by ARI (Atlassian Resource Identifier):

• jira.py rovo returns only results with ari:cloud:jira:...
• confluence.py rovo returns only results with ari:cloud:confluence:...

Output fields:

• id - Atlassian Resource Identifier (ARI)
• type - Content type
• title - Issue summary or page title
• url - Direct link
• text - Content preview (300 chars)

Jira Commands

# List projects
uv run --directory ${CLAUDE_PLUGIN_ROOT}/skills/jira-confluence scripts/jira.py projects

## List issue (ticket, task) types for a project
uv run --directory ${CLAUDE_PLUGIN_ROOT}/skills/jira-confluence scripts/jira.py types PROJ

# Fetch a ticket
uv run --directory ${CLAUDE_PLUGIN_ROOT}/skills/jira-confluence scripts/jira.py get PROJ-123

# Search with JQL
uv run --directory ${CLAUDE_PLUGIN_ROOT}/skills/jira-confluence scripts/jira.py search "project=DEMO AND status='In Progress'"

# Get comments
uv run --directory ${CLAUDE_PLUGIN_ROOT}/skills/jira-confluence scripts/jira.py comments PROJ-123

# List all statuses for issues (tickets) in a project
uv run --directory ${CLAUDE_PLUGIN_ROOT}/skills/jira-confluence scripts/jira.py statuses PROJ

Common JQL examples:

• assignee=currentUser() - My assigned issues
• project=PROJ AND sprint in openSprints() - Current sprint
• reporter=currentUser() AND created >= -7d - My recent issues
• labels=urgent AND status!=Done - Urgent incomplete items

Export issues to files

# Export to markdown files
uv run --directory ${CLAUDE_PLUGIN_ROOT}/skills/jira-confluence scripts/jira.py export "project=DEMO" --format markdown --output-dir ./exports/

# Export to stdout (yaml default)
uv run --directory ${CLAUDE_PLUGIN_ROOT}/skills/jira-confluence scripts/jira.py export "project=DEMO"

# Export to JSON
uv run --directory ${CLAUDE_PLUGIN_ROOT}/skills/jira-confluence scripts/jira.py export "project=DEMO" --format json

Edit

# Add comment to ticket
uv run --directory ${CLAUDE_PLUGIN_ROOT}/skills/jira-confluence scripts/jira.py comment PROJ-123 "This is my comment"

# Get available transitions
uv run --directory ${CLAUDE_PLUGIN_ROOT}/skills/jira-confluence scripts/jira.py transitions PROJ-123

# Transition ticket status
uv run --directory ${CLAUDE_PLUGIN_ROOT}/skills/jira-confluence scripts/jira.py transition PROJ-123 "In Progress"

# Or by transition ID
uv run --directory ${CLAUDE_PLUGIN_ROOT}/skills/jira-confluence scripts/jira.py transition PROJ-123 --id 21

Create ticket

uv run --directory ${CLAUDE_PLUGIN_ROOT}/skills/jira-confluence scripts/jira.py create PROJ --type Story --summary "My new story"
# With more options
uv run --directory ${CLAUDE_PLUGIN_ROOT}/skills/jira-confluence scripts/jira.py create PROJ --type Bug --summary "Bug title" --description "Details here" --priority High --labels "bug,urgent"
# With custom fields (for project-specific required fields)
uv run --directory ${CLAUDE_PLUGIN_ROOT}/skills/jira-confluence scripts/jira.py create PROJ --type Story --summary "My story" --field "Story Points=5" --field "Team=Platform"

Edit ticket

uv run --directory ${CLAUDE_PLUGIN_ROOT}/skills/jira-confluence scripts/jira.py edit PROJ-123 --summary "Updated title"
# Update multiple fields
uv run --directory ${CLAUDE_PLUGIN_ROOT}/skills/jira-confluence scripts/jira.py edit PROJ-123 --summary "New title" --description "New description"
# Update custom fields
uv run --directory ${CLAUDE_PLUGIN_ROOT}/skills/jira-confluence scripts/jira.py edit PROJ-123 --field "Story Points=8" --field "customfield_10001=value"

Assign ticket

uv run --directory ${CLAUDE_PLUGIN_ROOT}/skills/jira-confluence scripts/jira.py assign PROJ-123 <account_id>
# Assign to yourself
uv run --directory ${CLAUDE_PLUGIN_ROOT}/skills/jira-confluence scripts/jira.py assign PROJ-123 --me
# Unassign
uv run --directory ${CLAUDE_PLUGIN_ROOT}/skills/jira-confluence scripts/jira.py assign PROJ-123 --unassign

List fields for an issue type

uv run --directory ${CLAUDE_PLUGIN_ROOT}/skills/jira-confluence scripts/jira.py fields PROJ --type Story

Get current user info

uv run --directory ${CLAUDE_PLUGIN_ROOT}/skills/jira-confluence scripts/jira.py me

Lookup user by name or email

uv run --directory ${CLAUDE_PLUGIN_ROOT}/skills/jira-confluence scripts/jira.py lookup "John Doe"

Confluence Commands

# Fetch a page
uv run --directory ${CLAUDE_PLUGIN_ROOT}/skills/jira-confluence scripts/confluence.py get 123456789

# Search with CQL
uv run --directory ${CLAUDE_PLUGIN_ROOT}/skills/jira-confluence scripts/confluence.py search "type=page AND space=TEAM"

# Get all descendant pages (uses CQL ancestor= query for complete results)
uv run --directory ${CLAUDE_PLUGIN_ROOT}/skills/jira-confluence scripts/confluence.py children 123456789

# List spaces
uv run --directory ${CLAUDE_PLUGIN_ROOT}/skills/jira-confluence scripts/confluence.py spaces

Common CQL examples:

• type=page AND title~'architecture' - Pages with "architecture" in title
• space=TEAM AND lastModified >= now('-7d') - Recent team pages
• creator=currentUser() - My pages
• label='important' - Pages with label

Download page tree(s)

# Download a page and all its descendants with nested folders
uv run --directory ${CLAUDE_PLUGIN_ROOT}/skills/jira-confluence scripts/confluence.py tree 123456789 --output-dir ./exports/

# Download multiple page trees (e.g., sibling pages in a space)
uv run --directory ${CLAUDE_PLUGIN_ROOT}/skills/jira-confluence scripts/confluence.py tree 123456789 987654321 --output-dir ./exports/

# With JSON format instead of markdown
uv run --directory ${CLAUDE_PLUGIN_ROOT}/skills/jira-confluence scripts/confluence.py tree 123456789 --output-dir ./exports/ --format json

# Limit recursion depth
uv run --directory ${CLAUDE_PLUGIN_ROOT}/skills/jira-confluence scripts/confluence.py tree 123456789 --output-dir ./exports/ --max-depth 3

Creates properly nested folder structure with toc.md table of contents:

exports/
  toc.md                    # Table of contents with links
  Page_Title_123/
    index.md
    Child_Page_456/
      index.md
      Grandchild_789/
        index.md

Export pages to files

# Export to markdown files
uv run --directory ${CLAUDE_PLUGIN_ROOT}/skills/jira-confluence scripts/confluence.py export "space=TEAM" --format markdown --output-dir ./exports/

# Export to stdout (yaml default)
uv run --directory ${CLAUDE_PLUGIN_ROOT}/skills/jira-confluence scripts/confluence.py export "type=page AND title~'architecture'"

# Export to JSON
uv run --directory ${CLAUDE_PLUGIN_ROOT}/skills/jira-confluence scripts/confluence.py export "space=TEAM" --format json

Limitations

Jira JQL search limited to 100 results

The Atlassian MCP server doesn't return pagination tokens for JQL search responses, so results are limited to 100 issues per query. For projects with more issues, use specific JQL filters:

# Filter by date range
uv run --directory ${CLAUDE_PLUGIN_ROOT}/skills/jira-confluence scripts/jira.py search "project=PROJ AND created >= -30d"

# Filter by status
uv run --directory ${CLAUDE_PLUGIN_ROOT}/skills/jira-confluence scripts/jira.py search "project=PROJ AND status='In Progress'"

# Filter by assignee
uv run --directory ${CLAUDE_PLUGIN_ROOT}/skills/jira-confluence scripts/jira.py search "project=PROJ AND assignee=currentUser()"

Confluence CQL search supports pagination

Confluence search properly paginates through all results. Use --all flag with search:

uv run --directory ${CLAUDE_PLUGIN_ROOT}/skills/jira-confluence scripts/confluence.py search "space=TEAM" --all

Troubleshooting

Credential storage

All credentials are stored in ~/.atlassian-mcp/:

• tokens.json — OAuth access/refresh tokens
• config.json — site config (cloud ID, site URL, auth type)
• client_info.json — OAuth client registration

"Not authenticated" error

Run the login command shown in Setup above.

"Token expired" error

Run the login command again to re-authenticate. OAuth tokens auto-refresh, but refresh tokens can expire after extended periods of inactivity.

"No cloud ID" error

Re-authenticate by running the login command shown in Setup above.

"Permission denied" on write operations

Your OAuth token may lack write permissions. Re-authenticate to get new permissions:

uv run --directory ${CLAUDE_PLUGIN_ROOT}/skills/jira-confluence scripts/auth.py login

"Transition not found" error

The target status is not available from the current issue status. Use transitions command to see available options.

"Required field missing" or field validation errors

Projects often have custom required fields (e.g., Story Points, Team). To discover required fields:

uv run --directory ${CLAUDE_PLUGIN_ROOT}/skills/jira-confluence scripts/jira.py fields PROJ --type Story

Then add the required fields using --field:

uv run --directory ${CLAUDE_PLUGIN_ROOT}/skills/jira-confluence scripts/jira.py create PROJ --type Story --summary "Title" --field "customfield_10001=5"

Workflows

jira-status-update

Update ticket statuses based on recent git commits content. Matches commits to tickets by ticket IDs and drafts status update comments.

workflows/jira-status-update.md

jira-cleanup

Analyze active Jira tickets against the codebase to identify problems (vague descriptions, stale discussions, incorrect statuses, implemented features still open) and propose cleanup actions.

workflows/jira-cleanup.md