atlassian-mcp

--- name: atlassian-mcp description: 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. license: MIT metadata: author: https://github.com/Jeffallan version: "1.1.0" domain: platform triggers: Jira, Confluence, Atlassian, MCP, tickets, issues, wiki, JQL, CQL, sprint, backlog, project management role: expert scope: implementation output-format: code related-skills: mcp-developer, api-designer, security-reviewer --- # 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 1. **Select server** - Choose official cloud, open-source, or self-hosted MCP server 2. **Authenticate** - Configure OAuth 2.1, API tokens, or PAT credentials 3. **Design queries** - Write JQL for Jira, CQL for Confluence; validate with `maxResults=1` before full execution 4. **Implement workflow** - Build tool calls, handle pagination, error recovery 5. **Verify permissions** - Confirm required scopes with a read-only probe before any write or bulk operation 6. **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 ```json { "mcpServers": { "atlassian": { "command": "npx", "args": ["-y", "@sooperset/mcp-atlassian"], "env": { "JIRA_URL": "https://your-domain.atlassian.net", "JIRA_EMAIL": "[email protected]", "JIRA_API_TOKEN": "${JIRA_API_TOKEN}", "CONFLUENCE_URL": "https://your-domain.atlassian.net/wiki", "CONFLUENCE_EMAIL": "[email protected]", "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: 1. MCP server configuration (JSON/environment vars) 2. Query examples (JQL/CQL with explanations) 3. Tool call implementation with error handling 4. Authentication setup instructions 5. Brief explanation of permission requirements [Documentation](https://jeffallan.github.io/claude-skills/skills/platform/atlassian-mcp/)

[{"step":"Authenticate the MCP server with your Atlassian credentials. Use the Atlassian MCP tool's authentication command (e.g., `atlassian-mcp auth --username [EMAIL] --api-token [TOKEN] --domain [DOMAIN]`). Tip: Store your API token securely using a password manager.","action":"Run the authentication command once per session or save credentials in your MCP client's configuration."},{"step":"Specify the Atlassian product and action in your prompt. Use placeholders like [PROJECT_KEY], [TEAM], or [KEYWORD] to customize queries. Tip: For JQL queries, test them first in Jira's advanced search to ensure accuracy.","action":"Replace placeholders with your specific data (e.g., project keys, team names, or keywords) to generate targeted queries."},{"step":"Execute the action and review the results. For queries, verify the output matches your expectations (e.g., correct issues, pages, or sprints). Tip: Use the `limit` parameter in JQL queries to avoid overwhelming results (e.g., `ORDER BY created DESC LIMIT 50`).","action":"Check the AI's output for errors or missing data. If results are incomplete, refine your prompt with more specific criteria."},{"step":"Take follow-up actions based on the results. For example, update a ticket with new information, create a Confluence page from a template, or adjust sprint planning. Tip: Use the MCP tool's `update` or `create` commands to modify Atlassian data directly.","action":"Use the tool's output to inform your next steps (e.g., assigning a ticket, documenting a decision, or re-prioritizing work)."},{"step":"Debug issues with API calls or authentication errors. Check the MCP tool's logs for error messages and verify your credentials and permissions. Tip: Use the `debug` flag in the MCP tool to get detailed logs (e.g., `atlassian-mcp --debug query jira`).","action":"If the tool fails, review error messages and adjust your prompt or configuration (e.g., ensure the API token has the correct permissions)."}]