mcp-atlassian-extended

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

mcp-atlassian-extended is a Model Context Protocol (MCP) server for Jira and Confluence. It gives an AI assistant 22 tools, 15 resources, and 5 prompts for Jira and Confluence work. The tools create and update issues with custom fields, link issues, manage attachments, and search users. They also run agile boards and sprints, track project versions (API v2), read team calendars, and plan sprint capacity. It extends mcp-atlassian with zero tool overlap.

The server supports the MCP 2026-07-28 specification (often called MCP 2.0) and stays compatible with 2025-11-25 clients. It works with Claude Desktop, Claude Code, Cursor, Windsurf, VS Code Copilot, and any MCP-compatible client.

The server supports Jira Cloud, Jira Data Center, Confluence Cloud, and Confluence Data Center (self-hosted). It needs no Atlassian Premium plan.

Built with FastMCP, httpx, and Pydantic.

Protocol support

• The server implements the MCP 2026-07-28 specification, often called MCP 2.0.
• It stays compatible with 2025-11-25 clients.
• Transports: stdio (default) and streamable-http (recommended for remote clients). The sse transport still works, but the 2026-07-28 specification deprecates it, so the server prints a warning.
• The server uses no roots, sampling, logging, elicitation, or resource subscriptions. The 2026-07-28 deprecations do not affect it.
• Built on FastMCP 4.x and the MCP Python SDK 2.x.

Error results

Expected failures — a 404, a 401/403, a read-only refusal, an invalid argument — come back as a tool result with isError: true, so an MCP client sees the failure instead of a result that merely happens to contain the word error. The result body is the same {"error": …, "hint": …} object as before, with status_code and body when the failure came from the API; the hint names the fix. This object is the result's text content; structuredContent is not set, because a strict MCP client validates structuredContent against the tool's output schema even when isError is true, and the error envelope does not match it. Genuine bugs are still raised as protocol-level tool errors and logged with a traceback.

On success, a tool carries the same pretty-printed JSON as its text content and that JSON object as structuredContent — the pre-2.0 {"result": "<json string>"} wrapper is gone (a payload that is a JSON array, such as a multi-file upload response, carries text only, since structuredContent must be an object). Tools advertise no outputSchema: upstream fields pass through untyped, and a typed schema is opt-in per tool via output_schema= on @mcp.tool(...) when a client needs one.

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.

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

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

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

Basic auth wins. If you set both JIRA_USERNAME and JIRA_API_TOKEN, the server uses Basic auth and ignores any personal access token. The server uses Bearer auth only when the Cloud pair is incomplete. To force Bearer, unset JIRA_USERNAME and JIRA_API_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

Basic auth wins here too: CONFLUENCE_USERNAME + CONFLUENCE_API_TOKEN take precedence over any personal access token.

All Confluence calendar tools require the Team Calendars add-on (/rest/calendar-services/1.0/). On instances without it every calendar tool returns a 404 with a hint naming the add-on.

Optional settings

Compatibility

Tools (22)

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_issue(project_key="PROJ", summary="Q1 Auth Overhaul", issue_type="Epic")
→ 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="report.pdf")  # lands in ./atlassian-downloads/report.pdf (or ATLASSIAN_DOWNLOAD_DIR)

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_get_time_off(start_date="today", end_date="today", group_by_person=True)

"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). The server enforces this before any API call.
• Upload root restriction: jira_upload_attachment only reads files inside the upload root — ATLASSIAN_UPLOAD_DIR if set, otherwise the working directory. The path is resolved (following symlinks) before the containment check, so a symlink pointing outside the root is rejected; dotfiles and dot-directories below the root are refused. Size is capped at 100 MB.
• Download directory restriction: jira_download_attachment writes only into the download directory (ATLASSIAN_DOWNLOAD_DIR, default ./atlassian-downloads/, created on first use). save_path must be a bare file name — directories, absolute paths and dotfiles are rejected, not silently stripped. Existing files are never overwritten: a -1, -2 numeric suffix is added and the final path is returned. The downloaded body is capped at 100 MB, mirroring the upload cap. Add atlassian-downloads/ to your project's .gitignore.
• Desktop-client caveat: clients such as Claude Desktop launch stdio servers with a working directory of / or $HOME, which makes most of the filesystem the upload root (dotfiles excepted). Set ATLASSIAN_UPLOAD_DIR (and, if you like, ATLASSIAN_DOWNLOAD_DIR) explicitly for such clients.
• Migration (0.11 → 0.12): uploads are now restricted to ATLASSIAN_UPLOAD_DIR (default: the server's working directory) and dotfiles are refused — if your client uploads from ~/Downloads, set ATLASSIAN_UPLOAD_DIR=~/Downloads. Downloads now land in ./atlassian-downloads/ (or ATLASSIAN_DOWNLOAD_DIR) instead of the working directory, save_path is a file name only, and existing files are never overwritten.
• Download URL validation: The server validates each attachment download URL against the configured Jira URL domain to prevent SSRF.
• SSL verification: The server enables SSL verification by default for Jira and Confluence. Disable it only 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: The server reads tokens from environment variables at startup. It never stores them.

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. Use streamable-http for remote clients.
uvx mcp-atlassian-extended --transport streamable-http --port 9000

# sse still works, but the MCP 2026-07-28 spec deprecates it. The server prints a warning.
uvx mcp-atlassian-extended --transport sse --host 127.0.0.1 --port 8000

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

The --jira-token, --jira-api-token, --confluence-token and --confluence-api-token flags still work but are deprecated and hidden from --help: they expose the token to ps and shell history. Set JIRA_PAT / JIRA_API_TOKEN / CONFLUENCE_PAT / CONFLUENCE_API_TOKEN instead.

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

Partial configuration: You configure Jira and Confluence independently. Set either or both. The server always advertises all 22 tools. A tool for an unconfigured product returns a "not configured" error that names the variables to set. The server does not fail at startup.

FAQ

Does it support the MCP 2026-07-28 spec (MCP 2.0)?

Yes. It implements the MCP 2026-07-28 specification (MCP 2.0) and stays compatible with 2025-11-25 clients.

Which transports does it support?

It supports stdio (the default) and streamable-http (recommended for remote clients). The sse transport still works, but the 2026-07-28 specification deprecates it.

Is it read-only safe?

Yes. Set ATLASSIAN_READ_ONLY=true to disable every write operation. The server enforces this before any API call.

Does it work with self-hosted Jira and Confluence?

Yes. It supports Jira Cloud, Jira Data Center, Confluence Cloud, and Confluence Data Center. It uses the Jira REST API v2, which works on both Cloud and Server/Data Center.

What permissions and token scopes does it need?

It needs a Jira API token (Cloud) or a personal access token (Data Center). Each operation needs the matching Jira permission. See Required Permissions.

Does it replace mcp-atlassian?

No. It runs alongside mcp-atlassian with zero tool overlap. mcp-atlassian handles core search and CRUD. This server adds attachments, agile boards, versions, and calendars.

Do the Confluence tools need an add-on?

Yes. The three Confluence calendar tools need the Team Calendars add-on. Without it, they return a 404 with a hint that names the add-on.

How many tools does it provide?

It provides 22 tools, 15 resources, and 5 prompts for Jira and Confluence.

Related MCP Servers

• mcp-gitlab — GitLab integration (83 tools, 7 resources, 6 prompts)
• mcp-coda — Coda integration (53 tools, 12 resources, 5 prompts)
• mcp-argocd — Argo CD integration (37 tools, 7 resources, 7 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