mcp-atlassian-extended

Install: uvx mcp-atlassian-extended | PyPI | MCP Registry | Changelog

mcp-atlassian-extended is a Model Context Protocol (MCP) server that extends mcp-atlassian with 26 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, project versions (API v2), calendars, time-off tracking, and sprint capacity planning. Works with Claude Desktop, Claude Code, Cursor, Windsurf, VS Code Copilot, and any MCP-compatible client.

Supports Jira Cloud, Jira Data Center, Confluence Cloud, and Confluence Data Center (self-hosted). No Atlassian Premium required.

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, versions (API v2), 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, Gemini CLI), visit the Atlassian Extended MCP Installation Gateway.

Prerequisite: Install uv first (required for all uvx install flows). Install uv.

Claude Code

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

Windsurf & IntelliJ

Windsurf: Add to ~/.codeium/windsurf/mcp_config.json IntelliJ: Add to Settings | Tools | MCP Servers

Note: The actual server config starts at atlassian-extended inside the mcpServers object.

{
  "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"
      }
    }
  }
}

Gemini CLI

gemini mcp add -e JIRA_URL=https://your-company.atlassian.net -e JIRA_USERNAME=your.email@company.com -e JIRA_API_TOKEN=your_api_token -e CONFLUENCE_URL=https://your-company.atlassian.net/wiki -e CONFLUENCE_USERNAME=your.email@company.com -e CONFLUENCE_API_TOKEN=your_api_token atlassian-extended uvx mcp-atlassian-extended

pip / uv

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 (26)

Jira Issues

Jira Links

Jira Attachments

Jira Users

Jira Metadata

Jira Agile

Jira Versions

Confluence Calendars

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)

Version Management

"List versions for project PROJ"
→ jira_get_project_versions(project_key="PROJ")

"Create a new release version"
→ jira_create_version(project_key="PROJ", name="v2.0.0", release_date="2026-04-01")

"Mark version as released"
→ jira_update_version(version_id="200", released=True)

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.

Related MCP Servers

• mcp-gitlab — GitLab integration (76 tools, 6 resources, 5 prompts)
• mcp-coda — Coda.io integration (54 tools, 12 resources, 5 prompts)

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