mcp-atlassian-extended

mcp-atlassian-extended is a Model Context Protocol (MCP) server that extends mcp-atlassian with 23 tools, 15 resources, and 5 prompts for Jira and Confluence: issue creation with custom fields, issue links, attachments, agile boards, sprints, backlog management, user search, calendars, time-off tracking, and sprint capacity planning. Works with Claude Desktop, Claude Code, Cursor, Windsurf, VS Code Copilot, and any MCP-compatible client.

Built with FastMCP, httpx, and Pydantic.

Relationship to mcp-atlassian

This project runs alongside mcp-atlassian, not as a replacement. Configure both servers:

• mcp-atlassian handles: issues, search, transitions, comments, worklog, pages, Confluence search
• mcp-atlassian-extended handles: attachments, agile, users, fields, calendars, time-off

There is no tool overlap — this server only implements tools that mcp-atlassian lacks.

1-Click Installation

💡 Tip: For other AI assistants (Claude Code, Windsurf, IntelliJ), visit the Atlassian Extended MCP Installation Gateway.

claude mcp add atlassian-extended -- uvx mcp-atlassian-extended

{
  "mcpServers": {
    "atlassian-extended": {
      "command": "uvx",
      "args": ["mcp-atlassian-extended"],
      "env": {
        "JIRA_URL": "https://your-company.atlassian.net",
        "JIRA_USERNAME": "your.email@company.com",
        "JIRA_API_TOKEN": "your_api_token",
        "CONFLUENCE_URL": "https://your-company.atlassian.net/wiki",
        "CONFLUENCE_USERNAME": "your.email@company.com",
        "CONFLUENCE_API_TOKEN": "your_api_token"
      }
    }
  }
}

uv pip install mcp-atlassian-extended

Configuration

Jira Cloud (Basic Auth)

Jira Data Center / Self-Hosted (Bearer Token)

The server checks these environment variables in order — first match wins:

1. JIRA_PAT
2. JIRA_PERSONAL_TOKEN
3. JIRA_TOKEN

Confluence Cloud (Basic Auth)

Confluence Data Center / Self-Hosted (Bearer Token)

The server checks these environment variables in order — first match wins:

1. CONFLUENCE_PAT
2. CONFLUENCE_PERSONAL_TOKEN
3. CONFLUENCE_TOKEN

Optional settings

Compatibility

Tools (23)

Resources (15)

The server exposes curated Jira and Confluence workflow guides as MCP resources.

Prompts (5)

The server provides MCP prompts — reusable multi-tool workflow templates that clients can surface as slash commands.

Usage Examples

Issue Management

"Create a story in PROJ with custom story points"
→ jira_create_issue(project_key="PROJ", summary="Add OAuth login", issue_type="Story",
    custom_fields={"customfield_10004": 5})

"Update a ticket's priority and add labels"
→ jira_update_issue(issue_key="PROJ-123", fields={"priority": {"name": "High"}, "labels": ["urgent"]})

"Create an epic and link related stories"
→ jira_create_epic(project_key="PROJ", epic_name="Q1 Auth Overhaul")
→ jira_create_link(link_type="Relates", inward_issue="PROJ-100", outward_issue="PROJ-200")

Attachments

"List attachments on PROJ-123"
→ jira_get_attachments(issue_key="PROJ-123")

"Upload a screenshot to a ticket"
→ jira_upload_attachment(issue_key="PROJ-123", file_path="./screenshot.png")

"Download an attachment"
→ jira_download_attachment(content_url="https://jira.example.com/rest/api/2/attachment/content/456",
    save_path="./downloads/report.pdf")

Agile & Sprint Management

"Get the current sprint for board 42"
→ jira_get_board(board_id=42) → jira_get_sprint(sprint_id=7)

"Move tickets into the next sprint"
→ jira_move_to_sprint(sprint_id=8, issue_keys=["PROJ-1", "PROJ-2", "PROJ-3"])

"View backlog for board 42"
→ jira_backlog(board_id=42, max_results=50)

Time-Off & Sprint Capacity

"Who is out today?"
→ confluence_who_is_out(date="today")

"Get team time-off for the next two weeks"
→ confluence_get_time_off(start_date="today", end_date="+14d", group_by_person=True)

"Calculate sprint capacity accounting for PTO"
→ confluence_sprint_capacity(
    team_members=["Alice", "Bob", "Carol"],
    sprint_start="2025-03-03", sprint_end="2025-03-14")

Security Considerations

• Token scope: For Jira Cloud, use API tokens scoped to the minimum required permissions. For Data Center, use PATs with project-level access.
• Read-only mode: Set ATLASSIAN_READ_ONLY=true to disable all write operations (create, update, delete, upload). Enforced server-side before any API call.
• File upload validation: jira_upload_attachment validates file paths (no traversal, max 100MB, file must exist).
• Download path restriction: jira_download_attachment only accepts relative paths resolved within the working directory. Absolute paths and path traversal (../) are rejected.
• Download URL validation: Attachment download URLs are validated against the configured Jira URL domain to prevent SSRF.
• SSL verification: Enabled by default for both Jira and Confluence. Only disable for self-signed certificates in trusted networks.
• MCP tool annotations: Each tool declares readOnlyHint, destructiveHint, and idempotentHint for client-side permission prompts.
• No credential storage: Tokens are read from environment variables at startup and never persisted.

Rate Limits & Permissions

Rate Limits

Jira Cloud enforces per-user rate limits. When rate-limited, tools return a 429 error with a hint to wait. Confluence Calendar API calls may be slower due to the Team Calendars plugin architecture.

Required Permissions

CLI & Transport Options

# Default: stdio transport (for MCP clients)
uvx mcp-atlassian-extended

# HTTP transport (SSE or streamable-http)
uvx mcp-atlassian-extended --transport sse --host 127.0.0.1 --port 8000
uvx mcp-atlassian-extended --transport streamable-http --port 9000

# CLI overrides for config
uvx mcp-atlassian-extended --jira-url https://jira.example.com --jira-token xxx --read-only

The server loads .env files from the working directory automatically via python-dotenv.

Partial configuration: If only Jira credentials are set, the server starts with Jira tools only (no Confluence tools). The reverse also works — set only Confluence credentials to get calendar/time-off tools without Jira.

Attribution

Inspired by mcp-atlassian by sooperset. Architecture and patterns follow similar conventions.

Development

git clone https://github.com/vish288/mcp-atlassian-extended.git
cd mcp-atlassian-extended
uv sync --all-extras

uv run pytest --cov
uv run ruff check .
uv run ruff format --check .

License

MIT