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
Atlassian Cloud: connect to the hosted Atlassian Rovo MCP Server, then run /mcp to sign in with OAuth.
claude mcp add --transport http atlassian https://mcp.atlassian.com/v2/mcp
Server/Data Center: run the community mcp-atlassian server (sooperset) with personal access tokens.
{
"mcpServers": {
"atlassian": {
"command": "uvx",
"args": ["mcp-atlassian"],
"env": {
"JIRA_URL": "https://jira.internal.example.com",
"JIRA_PERSONAL_TOKEN": "${JIRA_PERSONAL_TOKEN}",
"CONFLUENCE_URL": "https://confluence.internal.example.com",
"CONFLUENCE_PERSONAL_TOKEN": "${CONFLUENCE_PERSONAL_TOKEN}"
}
}
}
}
Note: Always load tokens from environment variables or a secrets manager; never hardcode credentials. Tool names differ between servers, see references/mcp-server-setup.md.
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
Maintained by @jeffallan, Principal Consultant at Synergetic Solutions
Documentation
1---2name: atlassian-mcp3description: Integrates with Atlassian products to manage project tracking and documentation via MCP protocol. Use when querying Jira issues with JQL filters, creating and updating tickets with custom fields, searching or editing Confluence pages with CQL, managing sprints and backlogs, setting up MCP server authentication, syncing documentation, or debugging Atlassian API integrations.4license: MIT5metadata:6 source: https://skillmd.com/skills/tuyv/atlassian-mcp7 author: https://github.com/Jeffallan8 company: https://synergetic.solutions9 version: "1.2.0"10 domain: platform11 triggers: Jira, Confluence, Atlassian, MCP, tickets, issues, wiki, JQL, CQL, sprint, backlog, project management12 role: expert13 scope: implementation14 output-format: code15 related-skills: mcp-developer, api-designer, security-reviewer16---1718# Atlassian MCP Expert1920## When to Use This Skill2122- Querying Jira issues with JQL filters23- Searching or creating Confluence pages24- Automating sprint workflows and backlog management25- Setting up MCP server authentication (OAuth/API tokens)26- Syncing meeting notes to Jira tickets27- Generating documentation from issue data28- Debugging Atlassian API integration issues29- Choosing between official vs open-source MCP servers3031## Core Workflow32331. **Select server** - Choose official cloud, open-source, or self-hosted MCP server342. **Authenticate** - Configure OAuth 2.1, API tokens, or PAT credentials353. **Design queries** - Write JQL for Jira, CQL for Confluence; validate with `maxResults=1` before full execution364. **Implement workflow** - Build tool calls, handle pagination, error recovery375. **Verify permissions** - Confirm required scopes with a read-only probe before any write or bulk operation386. **Deploy** - Configure IDE integration, test permissions, monitor rate limits3940## Reference Guide4142Load detailed guidance based on context:4344| Topic | Reference | Load When |45|-------|-----------|-----------|46| Server Setup | `references/mcp-server-setup.md` | Installation, choosing servers, configuration |47| Jira Operations | `references/jira-queries.md` | JQL syntax, issue CRUD, sprints, boards, issue linking |48| Confluence Ops | `references/confluence-operations.md` | CQL search, page creation, spaces, comments |49| Authentication | `references/authentication-patterns.md` | OAuth 2.0, API tokens, permission scopes |50| Common Workflows | `references/common-workflows.md` | Issue triage, doc sync, sprint automation |5152## Quick-Start Examples5354### JQL Query Samples55```56# Open issues assigned to current user in a sprint57project = PROJ AND status = "In Progress" AND assignee = currentUser() ORDER BY priority DESC5859# Unresolved bugs created in the last 7 days60project = PROJ AND issuetype = Bug AND status != Done AND created >= -7d ORDER BY created DESC6162# Validate before bulk: test with maxResults=1 first63project = PROJ AND sprint in openSprints() AND status = Open ORDER BY created DESC64```6566### CQL Query Samples67```68# Find pages updated in a specific space recently69space = "ENG" AND type = page AND lastModified >= "2024-01-01" ORDER BY lastModified DESC7071# Search page text for a keyword72space = "ENG" AND type = page AND text ~ "deployment runbook"73```7475### Minimal MCP Server Configuration76Atlassian Cloud: connect to the hosted Atlassian Rovo MCP Server, then run `/mcp` to sign in with OAuth.77```bash78claude mcp add --transport http atlassian https://mcp.atlassian.com/v2/mcp79```8081Server/Data Center: run the community `mcp-atlassian` server (sooperset) with personal access tokens.82```json83{84 "mcpServers": {85 "atlassian": {86 "command": "uvx",87 "args": ["mcp-atlassian"],88 "env": {89 "JIRA_URL": "https://jira.internal.example.com",90 "JIRA_PERSONAL_TOKEN": "${JIRA_PERSONAL_TOKEN}",91 "CONFLUENCE_URL": "https://confluence.internal.example.com",92 "CONFLUENCE_PERSONAL_TOKEN": "${CONFLUENCE_PERSONAL_TOKEN}"93 }94 }95 }96}97```98> **Note:** Always load tokens from environment variables or a secrets manager; never hardcode credentials. Tool names differ between servers, see `references/mcp-server-setup.md`.99100## Constraints101102### MUST DO103- Respect user permissions and workspace access controls104- Validate JQL/CQL queries before execution (use `maxResults=1` probe first)105- Handle rate limits with exponential backoff106- Use pagination for large result sets (50-100 items per page)107- Implement error recovery for network failures108- Log API calls for debugging and audit trails109- Test with read-only operations first110- Document required permission scopes111- Confirm before any write or bulk operation against production data112113### MUST NOT DO114- Hardcode API tokens or OAuth secrets in code115- Ignore rate limit headers from Atlassian APIs116- Create issues without validating required fields117- Skip input sanitization on user-provided query strings118- Deploy without testing permission boundaries119- Update production data without confirmation prompts120- Mix different authentication methods in same session121- Expose sensitive issue data in logs or error messages122123## Output Templates124125When implementing Atlassian MCP features, provide:1261. MCP server configuration (JSON/environment vars)1272. Query examples (JQL/CQL with explanations)1283. Tool call implementation with error handling1294. Authentication setup instructions1305. Brief explanation of permission requirements131132Maintained by [@jeffallan](https://github.com/jeffallan), Principal Consultant at [Synergetic Solutions](https://synergetic.solutions)133134[Documentation](https://jeffallan.github.io/claude-skills/skills/platform/atlassian-mcp/)