Atlassian MCP Expert

When to Use This Skill

• Querying Jira issues with JQL filters

• Searching or creating Confluence pages

• Automating sprint workflows and backlog management

• Setting up MCP server authentication (OAuth/API tokens)

• Syncing meeting notes to Jira tickets

• Generating documentation from issue data

• Debugging Atlassian API integration issues

• Choosing between official vs open-source MCP servers

Core Workflow

• Select server - Choose official cloud, open-source, or self-hosted MCP server

• Authenticate - Configure OAuth 2.1, API tokens, or PAT credentials

• Design queries - Write JQL for Jira, CQL for Confluence; validate with maxResults=1 before full execution

• Implement workflow - Build tool calls, handle pagination, error recovery

• Verify permissions - Confirm required scopes with a read-only probe before any write or bulk operation

• Deploy - Configure IDE integration, test permissions, monitor rate limits

Reference Guide

Load detailed guidance based on context:

Topic

Reference

Load When

Server Setup

references/mcp-server-setup.md

Installation, choosing servers, configuration

Jira Operations

references/jira-queries.md

JQL syntax, issue CRUD, sprints, boards, issue linking

Confluence Ops

references/confluence-operations.md

CQL search, page creation, spaces, comments

Authentication

references/authentication-patterns.md

OAuth 2.0, API tokens, permission scopes

Common Workflows

references/common-workflows.md

Issue triage, doc sync, sprint automation

Quick-Start Examples

JQL Query Samples

# Open issues assigned to current user in a sprint

project = PROJ AND status = "In Progress" AND assignee = currentUser() ORDER BY priority DESC

# Unresolved bugs created in the last 7 days

project = PROJ AND issuetype = Bug AND status != Done AND created >= -7d ORDER BY created DESC

# Validate before bulk: test with maxResults=1 first

project = PROJ AND sprint in openSprints() AND status = Open ORDER BY created DESC

CQL Query Samples

# Find pages updated in a specific space recently

space = "ENG" AND type = page AND lastModified >= "2024-01-01" ORDER BY lastModified DESC

# Search page text for a keyword

space = "ENG" AND type = page AND text ~ "deployment runbook"

Minimal MCP Server Configuration

{

  "mcpServers": {

    "atlassian": {

      "command": "npx",

      "args": ["-y", "@sooperset/mcp-atlassian"],

      "env": {

        "JIRA_URL": "https://your-domain.atlassian.net",

        "JIRA_EMAIL": "user@example.com",

        "JIRA_API_TOKEN": "${JIRA_API_TOKEN}",

        "CONFLUENCE_URL": "https://your-domain.atlassian.net/wiki",

        "CONFLUENCE_EMAIL": "user@example.com",

        "CONFLUENCE_API_TOKEN": "${CONFLUENCE_API_TOKEN}"

      }

    }

  }

}

Note: Always load JIRA_API_TOKEN and CONFLUENCE_API_TOKEN from environment variables or a secrets manager — never hardcode credentials.

Constraints

MUST DO

• Respect user permissions and workspace access controls

• Validate JQL/CQL queries before execution (use maxResults=1 probe first)

• Handle rate limits with exponential backoff

• Use pagination for large result sets (50-100 items per page)

• Implement error recovery for network failures

• Log API calls for debugging and audit trails

• Test with read-only operations first

• Document required permission scopes

• Confirm before any write or bulk operation against production data

MUST NOT DO

• Hardcode API tokens or OAuth secrets in code

• Ignore rate limit headers from Atlassian APIs

• Create issues without validating required fields

• Skip input sanitization on user-provided query strings

• Deploy without testing permission boundaries

• Update production data without confirmation prompts

• Mix different authentication methods in same session

• Expose sensitive issue data in logs or error messages

Output Templates

When implementing Atlassian MCP features, provide:

• MCP server configuration (JSON/environment vars)

• Query examples (JQL/CQL with explanations)

• Tool call implementation with error handling

• Authentication setup instructions

• Brief explanation of permission requirements

Documentation