MCP Atlassian Extended

mcp-atlassian-extended

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

uvx mcp-atlassian-extended                          # with writes

MCP_READ_ONLY=true uvx mcp-atlassian-extended # locked read-only: write tools are not listed

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. Runs in one of two modes: with writes, or locked read-only (MCP_READ_ONLY=true) so the 10 write tools are never offered to the model.

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": " "} 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](https://vish288.github.io/mcp-install?server=mcp-atlassian-extended).

Manual Setup Guides (Click to expand)

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

Claude Code

# with writes

claude mcp add atlassian-extended \ -e JIRA_URL=https://your-company.atlassian.net -e JIRA_USERNAME=your.email@company.com -e JIRA_API_TOKEN=your_api_token \ -- uvx mcp-atlassian-extended

locked read-only: write tools are not listed

claude mcp add atlassian-extended -e MCP_READ_ONLY=true \ -e JIRA_URL=https://your-company.atlassian.net -e JIRA_USERNAME=your.email@company.com -e JIRA_API_TOKEN=your_api_token \ -- 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.

Remove MCP_READ_ONLY to allow writes.

{

"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", "MCP_READ_ONLY": "true" } } } }

Gemini CLI

# with writes

gemini mcp add -s user -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

locked read-only

gemini mcp add -s user -e MCP_READ_ONLY=true -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

VS Code

Add to .vscode/mcp.json. Remove MCP_READ_ONLY to allow writes.

{

"servers": { "atlassian-extended": { "type": "stdio", "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", "MCP_READ_ONLY": "true" } } } }

Codex

# with writes

codex mcp add atlassian-extended --env JIRA_URL=https://your-company.atlassian.net --env JIRA_USERNAME=your.email@company.com --env JIRA_API_TOKEN=your_api_token -- uvx mcp-atlassian-extended

locked read-only

codex mcp add atlassian-extended --env MCP_READ_ONLY=true --env JIRA_URL=https://your-company.atlassian.net --env JIRA_USERNAME=your.email@company.com --env JIRA_API_TOKEN=your_api_token -- uvx mcp-atlassian-extended

pip / uv

uv pip install mcp-atlassian-extended

Drop MCP_READ_ONLY to allow writes. On a shared or hosted server put it in the deployer's env, not the client config.

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

| `ATLAS