mcp-atlassian-extended 0.4.0

Extended MCP tools for Jira and Confluence — attachments, agile boards, sprints, calendars

mcp-atlassian-extended

mcp-atlassian-extended is a Model Context Protocol (MCP) server that extends mcp-atlassian with 23 additional tools 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.

Manual Setup Guides (Click to expand)

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": "[e-mail]",
        "JIRA_API_TOKEN": "your_api_token",
        "CONFLUENCE_URL": "https://your-company.atlassian.net/wiki",
        "CONFLUENCE_USERNAME": "[e-mail]",
        "CONFLUENCE_API_TOKEN": "your_api_token"
      }
    }
  }
}

pip / uv

uv pip install mcp-atlassian-extended

Configuration

Jira Cloud (Basic Auth)

Variable	Required	Default	Description
JIRA_URL	Yes	-	Jira instance URL (e.g. https://your-company.atlassian.net)
JIRA_USERNAME	Yes	-	Email address for Jira Cloud
JIRA_API_TOKEN	Yes	-	API token from id.atlassian.com/manage-profile/security/api-tokens

Jira Data Center / Self-Hosted (Bearer Token)

Variable	Required	Default	Description
JIRA_URL	Yes	-	Jira instance URL
JIRA_PAT	Yes	-	Personal access token

Also accepts: JIRA_PERSONAL_TOKEN, JIRA_TOKEN

Confluence Cloud (Basic Auth)

Variable	Required	Default	Description
CONFLUENCE_URL	Yes	-	Confluence URL (e.g. https://your-company.atlassian.net/wiki)
CONFLUENCE_USERNAME	Yes	-	Email address for Confluence Cloud
CONFLUENCE_API_TOKEN	Yes	-	API token (same as Jira if same Atlassian account)

Confluence Data Center / Self-Hosted (Bearer Token)

Variable	Required	Default	Description
CONFLUENCE_URL	Yes	-	Confluence instance URL
CONFLUENCE_PAT	Yes	-	Personal access token

Also accepts: CONFLUENCE_PERSONAL_TOKEN, CONFLUENCE_TOKEN

Optional settings

Variable	Default	Description
ATLASSIAN_READ_ONLY	false	Set to true to globally disable write operations across tools
JIRA_TIMEOUT	30	HTTP request timeout for Jira in seconds
JIRA_SSL_VERIFY	true	Set to false to skip SSL verification for Jira
CONFLUENCE_TIMEOUT	30	HTTP request timeout for Confluence in seconds
CONFLUENCE_SSL_VERIFY	true	Set to false to skip SSL verification for Confluence

Compatibility

Client	Supported	Install Method
Claude Desktop	Yes	claude_desktop_config.json
Claude Code	Yes	claude mcp add
Cursor	Yes	One-click deeplink or .cursor/mcp.json
Windsurf	Yes	~/.codeium/windsurf/mcp_config.json
VS Code Copilot	Yes	.vscode/mcp.json
Any MCP client	Yes	stdio or HTTP transport

Tools (23)

Category	Count	Tools
Jira Issues	3	create (with custom fields), update (with custom fields), create epic
Jira Links	2	create link, delete link
Jira Attachments	4	get, upload, download, delete
Jira Users	1	search by name/email
Jira Metadata	3	list projects, list fields, backlog
Jira Agile	4	get board, board config, get sprint, move to sprint
Confluence Calendars	6	list, search, time-off, who-is-out, person time-off, sprint capacity

Full tool reference (click to expand)

Jira Issues

Tool	Description
jira_create_issue	Create issue with standard and custom fields
jira_update_issue	Update issue fields and custom fields
jira_create_epic	Create an epic (sets issue type automatically)

Jira Links

Tool	Description
jira_create_link	Create a link between two issues (Relates, Blocks, etc.)
jira_delete_link	Delete an issue link by ID

Jira Attachments

Tool	Description
jira_get_attachments	List attachments on an issue
jira_upload_attachment	Upload file to issue
jira_download_attachment	Download attachment to local file
jira_delete_attachment	Delete an attachment

Jira Users

Tool	Description
jira_search_users	Search users by name/email

Jira Metadata

Tool	Description
jira_list_projects	List all accessible projects
jira_list_fields	List fields (with search/custom filter)
jira_backlog	Get backlog issues for a board

Jira Agile

Tool	Description
jira_get_board	Get board details
jira_board_config	Get board column configuration
jira_get_sprint	Get sprint details
jira_move_to_sprint	Move issues to a sprint

Confluence Calendars

Tool	Description
confluence_list_calendars	List all calendars
confluence_search_calendars	Search calendars by name/space
confluence_get_time_off	Get time-off events for date range
confluence_who_is_out	Check who is out on a date
confluence_get_person_time_off	Get person's time-off events
confluence_sprint_capacity	Calculate sprint capacity with time-off

Resources (15)

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

URI	Name
resource://rules/jira-hierarchy	Jira Issue Hierarchy
resource://rules/jira-ticket-writing	Jira Ticket Writing Standards
resource://rules/acceptance-criteria	Acceptance Criteria Standards
resource://rules/sprint-hygiene	Sprint Hygiene Rules
resource://rules/jira-workflow	Jira Workflow & Automation
resource://rules/issue-linking	Issue Linking Best Practices
resource://guides/story-points	Story Point Estimation
resource://guides/definition-of-done	Definition of Done Checklists
resource://guides/jira-labels	Jira Label Taxonomy
resource://guides/jql-library	JQL Query Library
resource://guides/custom-fields	Jira Custom Field Governance
resource://guides/confluence-spaces	Confluence Space Organization
resource://guides/agile-ceremonies	Agile Ceremony Standards
resource://guides/git-jira-integration	Git-Jira Integration Patterns
resource://templates/confluence-pages	Confluence Page Templates

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.
• 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

Operation	Minimum Jira Permission
List projects, fields, boards	Browse Projects
Search users	Browse Users
Create/update issues, epics	Create Issues + Edit Issues
Create/delete issue links	Link Issues
Upload/delete attachments	Create Attachments + Delete Own Attachments
Move issues to sprint	Manage Sprints
Confluence calendars/time-off	View space content

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