Atlassian

Atlassian Skill (Jira + Confluence)

Reference guide for using mcp__atlassian__ MCP tools to interact with Jira and Confluence on your Atlassian site.

Before first use, fill in the Site Configuration section at the bottom of this file with your Atlassian site name, default project key, and env var names — the examples throughout use placeholder values (PROJ, your-site).

Quick Reference: Common Operations

Jira

Searching Issues

Use JQL (Jira Query Language) with jira_search:

# Issues assigned to current user
assignee = currentUser() AND status != Done

# Recent bugs in a project
project = PROJ AND issuetype = Bug AND created >= -7d

# Sprint issues
sprint in openSprints() AND project = PROJ

# Text search
summary ~ "checkout" OR description ~ "checkout"

# Combined filters
project = PROJ AND status = "In Progress" AND priority = High ORDER BY updated DESC

Default fields: summary,status,assignee,priority. Use fields: "*all" for full details including description, comments, links.

Creating Issues

Required: project_key, summary, issue_type (Task, Bug, Story, Epic, Subtask).

Optional: description, assignee, components, dev_assignee, pm_assignee, design_assignee, additional_fields.

Custom assignee fields (dev_assignee, pm_assignee, design_assignee) accept email, name, or account ID.

Updating Issues

Pass a fields dict to jira_update_issue:

{"summary": "New title", "priority": {"name": "High"}, "labels": ["backend", "urgent"]}

For custom fields, use additional_fields or find field IDs with jira_get_custom_field_ids.

Transitions (Status Changes)

Always get available transitions first:

1. jira_get_transitions with issue_key -- returns available transition IDs
2. jira_transition_issue with issue_key and transition_id

Never hardcode transition IDs -- they vary by project workflow.

Issue Links

• jira_create_issue_link -- link two issues (Blocks, Duplicate, Relates to)
• jira_link_to_epic -- add issue to epic
• jira_get_link_types -- discover available link types

Sprint Management

1. jira_get_agile_boards -- find board ID (filter by project_key or board_name)
2. jira_get_sprints_from_board -- list sprints (filter by state: active/future/closed)
3. jira_get_sprint_issues -- get issues in a sprint
4. jira_move_issues_to_sprint -- move issues to a sprint
5. jira_create_sprint / jira_update_sprint -- manage sprints

Bulk Operations

• jira_batch_create_issues -- create multiple issues at once (JSON array of issue objects)
• jira_batch_get_changelogs -- get change history for multiple issues

Other Jira Tools

Confluence

Reading Pages

Two lookup methods:

1. By page_id (preferred): confluence_get_page with page_id
2. By title + space: confluence_get_page with title and space_key

Returns markdown by default. Set convert_to_markdown: false for raw HTML.

Searching Pages

confluence_search does exact title matching. Use spaces_filter (comma-separated space IDs) to narrow results.

To discover spaces: confluence_get_spaces.

Page Hierarchy

Creating & Updating Pages

• confluence_create_page: requires space_key, title, content. Content format defaults to markdown. Optional parent_id.
• confluence_update_page: requires page_id, title, content. Optional version_comment, parent_id.

Attachments & Images

1. confluence_get_page_attachments -- list attachments on a page
2. confluence_download_image -- download attachment content (base64 for binary, text for text)
3. confluence_upload_attachment -- upload file (base64 content)
4. confluence_delete_attachment -- remove attachment

Other Confluence Tools

Common Patterns

Find and update an issue

1. jira_search(jql="key = PROJ-123", fields="*all")
2. jira_get_transitions(issue_key="PROJ-123")
3. jira_transition_issue(issue_key="PROJ-123", transition_id="31")
4. jira_add_comment(issue_key="PROJ-123", comment="Done - deployed to staging")

Create issue with epic link

1. jira_create_issue(project_key="PROJ", summary="...", issue_type="Task")
2. jira_link_to_epic(issue_key="PROJ-NEW", epic_key="PROJ-100")

Document a decision in Confluence

1. confluence_get_spaces()  -- find target space
2. confluence_search(query="Architecture Decisions", spaces_filter="...")
3. confluence_create_page(space_key="ENG", title="ADR-042: ...", content="...", parent_id="12345")

Look up user then assign

1. jira_search_user(query="your-name") or jira_get_user_profile(user_identifier="you@example.com")
2. jira_assign_issue(issue_key="PROJ-123", account_id="...")

Site Configuration

Fill these in for your organization:

• Site: {{your-site}} (https://{{your-site}}.atlassian.net)
• User: {{you@example.com}}
• Default project key: {{PROJ}} — replace PROJ in the examples above with your project's key
• Env vars (in ~/.zshrc): $ATLASSIAN_SITE_URL, $ATLASSIAN_USER_EMAIL, $ATLASSIAN_API_TOKEN
• Default site param: {{your-site}} (all tools default to this)

Use list_atlassian_sites to see other available sites if needed.

REST API via curl (Fallback)

When MCP tools are unavailable or fail to connect, use the Jira/Confluence REST API directly via curl. Auth uses env vars from ~/.zshrc.

Auth pattern: source ~/.zshrc 2>/dev/null; curl -s -u "$ATLASSIAN_USER_EMAIL:$ATLASSIAN_API_TOKEN"

Jira REST API (v3)

Base: $ATLASSIAN_SITE_URL/rest/api/3

# Get issue
curl -s -u "$ATLASSIAN_USER_EMAIL:$ATLASSIAN_API_TOKEN" \
  "$ATLASSIAN_SITE_URL/rest/api/3/issue/PROJ-123?fields=summary,status,assignee,priority,description"

# Search with JQL
curl -s -u "$ATLASSIAN_USER_EMAIL:$ATLASSIAN_API_TOKEN" \
  "$ATLASSIAN_SITE_URL/rest/api/3/search?jql=project%3DPROJ%20AND%20status%3D%22In%20Progress%22&maxResults=20&fields=summary,status,assignee"

# Create issue
curl -s -u "$ATLASSIAN_USER_EMAIL:$ATLASSIAN_API_TOKEN" \
  -X POST -H "Content-Type: application/json" \
  "$ATLASSIAN_SITE_URL/rest/api/3/issue" \
  -d '{"fields":{"project":{"key":"PROJ"},"summary":"Title","issuetype":{"name":"Task"}}}'

# Update issue fields
curl -s -u "$ATLASSIAN_USER_EMAIL:$ATLASSIAN_API_TOKEN" \
  -X PUT -H "Content-Type: application/json" \
  "$ATLASSIAN_SITE_URL/rest/api/3/issue/PROJ-123" \
  -d '{"fields":{"summary":"Updated title","priority":{"name":"High"}}}'

# Get transitions
curl -s -u "$ATLASSIAN_USER_EMAIL:$ATLASSIAN_API_TOKEN" \
  "$ATLASSIAN_SITE_URL/rest/api/3/issue/PROJ-123/transitions"

# Transition issue
curl -s -u "$ATLASSIAN_USER_EMAIL:$ATLASSIAN_API_TOKEN" \
  -X POST -H "Content-Type: application/json" \
  "$ATLASSIAN_SITE_URL/rest/api/3/issue/PROJ-123/transitions" \
  -d '{"transition":{"id":"31"}}'

# Add comment
curl -s -u "$ATLASSIAN_USER_EMAIL:$ATLASSIAN_API_TOKEN" \
  -X POST -H "Content-Type: application/json" \
  "$ATLASSIAN_SITE_URL/rest/api/3/issue/PROJ-123/comment" \
  -d '{"body":{"type":"doc","version":1,"content":[{"type":"paragraph","content":[{"type":"text","text":"Comment text"}]}]}}'

# Assign issue
curl -s -u "$ATLASSIAN_USER_EMAIL:$ATLASSIAN_API_TOKEN" \
  -X PUT -H "Content-Type: application/json" \
  "$ATLASSIAN_SITE_URL/rest/api/3/issue/PROJ-123/assignee" \
  -d '{"accountId":"ACCOUNT_ID"}'

# List projects
curl -s -u "$ATLASSIAN_USER_EMAIL:$ATLASSIAN_API_TOKEN" \
  "$ATLASSIAN_SITE_URL/rest/api/3/project"

Confluence REST API (v2)

Base: $ATLASSIAN_SITE_URL/wiki/api/v2

# Get page by ID
curl -s -u "$ATLASSIAN_USER_EMAIL:$ATLASSIAN_API_TOKEN" \
  "$ATLASSIAN_SITE_URL/wiki/api/v2/pages/PAGE_ID?body-format=storage"

# Search pages by title
curl -s -u "$ATLASSIAN_USER_EMAIL:$ATLASSIAN_API_TOKEN" \
  "$ATLASSIAN_SITE_URL/wiki/api/v2/pages?title=Page%20Title&space-id=SPACE_ID"

# List spaces
curl -s -u "$ATLASSIAN_USER_EMAIL:$ATLASSIAN_API_TOKEN" \
  "$ATLASSIAN_SITE_URL/wiki/api/v2/spaces"

# Get child pages
curl -s -u "$ATLASSIAN_USER_EMAIL:$ATLASSIAN_API_TOKEN" \
  "$ATLASSIAN_SITE_URL/wiki/api/v2/pages/PAGE_ID/children"

# CQL search (legacy v1 - more powerful)
curl -s -u "$ATLASSIAN_USER_EMAIL:$ATLASSIAN_API_TOKEN" \
  "$ATLASSIAN_SITE_URL/wiki/rest/api/content/search?cql=space%3DENG%20AND%20type%3Dpage%20AND%20title~%22search%20term%22"

Parsing Jira responses

Jira v3 uses ADF (Atlassian Document Format) for description/comments. Extract text with:

| python3 -c "
import json, sys
def extract_text(node):
    if isinstance(node, dict):
        t = node.get('text','')
        for c in node.get('content',[]):
            t += extract_text(c)
        return t
    return ''
d = json.load(sys.stdin)
f = d['fields']
print(f'Key: {d[\"key\"]}')
print(f'Summary: {f[\"summary\"]}')
print(f'Status: {f[\"status\"][\"name\"]}')
print(f'Description: {extract_text(f.get(\"description\",{}))}')
"

When to use curl vs MCP tools

• MCP tools available and connected: prefer MCP (cleaner, structured responses)
• MCP auth failed or server not connected: use curl with env vars
• Bulk/complex queries: curl gives more control over pagination, fields, expand
• Always source ~/.zshrc 2>/dev/null before curl to load env vars

Common Mistakes

• Hardcoding transition IDs -- always call jira_get_transitions first; IDs differ per workflow
• Using fields: "*all" on search -- returns too much data; specify only needed fields for search, use *all only on jira_get_issue
• Forgetting pagination -- most list tools have limit (default 10-25) and start_at; check if results are truncated
• Confluence search is exact title -- not fuzzy; use confluence_get_page_children to browse hierarchies instead