{
"markdown": "# mcp-atlassian-extended\n\n[](https://pypi.org/project/mcp-atlassian-extended/)\n[](https://pypi.org/project/mcp-atlassian-extended/)\n[](https://pypi.org/project/mcp-atlassian-extended/)\n[](https://opensource.org/licenses/MIT)\n[](https://github.com/vish288/mcp-atlassian-extended/actions/workflows/tests.yml)\n[](https://registry.modelcontextprotocol.io)\n\n\n\n**Install:** `uvx mcp-atlassian-extended` | [PyPI](https://pypi.org/project/mcp-atlassian-extended/) | [MCP Registry](https://registry.modelcontextprotocol.io) | [Changelog](https://github.com/vish288/mcp-atlassian-extended/releases)\n\n**mcp-atlassian-extended** is a [Model Context Protocol (MCP)](https://modelcontextprotocol.io/) server that extends [mcp-atlassian](https://github.com/sooperset/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.\n\nSupports Jira Cloud, Jira Data Center, Confluence Cloud, and Confluence Data Center (self-hosted). No Atlassian Premium required.\n\nBuilt with [FastMCP](https://github.com/jlowin/fastmcp), [httpx](https://www.python-httpx.org/), and [Pydantic](https://docs.pydantic.dev/).\n\n## Relationship to mcp-atlassian\n\nThis project runs alongside [mcp-atlassian](https://github.com/sooperset/mcp-atlassian), not as a replacement. Configure both servers:\n\n- **mcp-atlassian** handles: issues, search, transitions, comments, worklog, pages, Confluence search\n- **mcp-atlassian-extended** handles: attachments, agile, users, fields, versions (API v2), calendars, time-off\n\nThere is no tool overlap ā this server only implements tools that mcp-atlassian lacks.\n\n## 1-Click Installation\n\n[](https://vish288.github.io/mcp-install?server=mcp-atlassian-extended&install=cursor)\n\n[](https://vish288.github.io/mcp-install?server=mcp-atlassian-extended&install=vscode) [](https://vish288.github.io/mcp-install?server=mcp-atlassian-extended&install=vscode-insiders)\n\n> **š” 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)**.\n\n\nManual Setup Guides (Click to expand)
\n
\n\n> Prerequisite: Install `uv` first (required for all `uvx` install flows). [Install uv](https://docs.astral.sh/uv/getting-started/installation/).\n\n### Claude Code\n\n```bash\nclaude mcp add atlassian-extended -- uvx mcp-atlassian-extended\n```\n\n### Windsurf & IntelliJ\n\n**Windsurf:** Add to `~/.codeium/windsurf/mcp_config.json`\n**IntelliJ:** Add to `Settings | Tools | MCP Servers`\n\n> **Note:** The actual server config starts at `atlassian-extended` inside the `mcpServers` object.\n\n```json\n{\n \"mcpServers\": {\n \"atlassian-extended\": {\n \"command\": \"uvx\",\n \"args\": [\"mcp-atlassian-extended\"],\n \"env\": {\n \"JIRA_URL\": \"https://your-company.atlassian.net\",\n \"JIRA_USERNAME\": \"your.email@company.com\",\n \"JIRA_API_TOKEN\": \"your_api_token\",\n \"CONFLUENCE_URL\": \"https://your-company.atlassian.net/wiki\",\n \"CONFLUENCE_USERNAME\": \"your.email@company.com\",\n \"CONFLUENCE_API_TOKEN\": \"your_api_token\"\n }\n }\n }\n}\n```\n\n### Gemini CLI\n\n```bash\ngemini 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\n```\n\n### pip / uv\n\n```bash\nuv pip install mcp-atlassian-extended\n```\n\n \n\n## Configuration\n\n### Jira Cloud (Basic Auth)\n\n| Variable | Required | Default | Description |\n|----------|----------|---------|-------------|\n| `JIRA_URL` | **Yes** | - | Jira instance URL (e.g. `https://your-company.atlassian.net`) |\n| `JIRA_USERNAME` | **Yes** | - | Email address for Jira Cloud |\n| `JIRA_API_TOKEN` | **Yes** | - | API token from [id.atlassian.com/manage-profile/security/api-tokens](https://id.atlassian.com/manage-profile/security/api-tokens) |\n\n### Jira Data Center / Self-Hosted (Bearer Token)\n\n| Variable | Required | Default | Description |\n|----------|----------|---------|-------------|\n| `JIRA_URL` | **Yes** | - | Jira instance URL |\n| `JIRA_PAT` | **Yes** | - | Personal access token (see fallback order below) |\n\nThe server checks these environment variables in order ā first match wins:\n\n1. `JIRA_PAT`\n2. `JIRA_PERSONAL_TOKEN`\n3. `JIRA_TOKEN`\n\n### Confluence Cloud (Basic Auth)\n\n| Variable | Required | Default | Description |\n|----------|----------|---------|-------------|\n| `CONFLUENCE_URL` | **Yes** | - | Confluence URL (e.g. `https://your-company.atlassian.net/wiki`) |\n| `CONFLUENCE_USERNAME` | **Yes** | - | Email address for Confluence Cloud |\n| `CONFLUENCE_API_TOKEN` | **Yes** | - | API token (same as Jira if same Atlassian account) |\n\n### Confluence Data Center / Self-Hosted (Bearer Token)\n\n| Variable | Required | Default | Description |\n|----------|----------|---------|-------------|\n| `CONFLUENCE_URL` | **Yes** | - | Confluence instance URL |\n| `CONFLUENCE_PAT` | **Yes** | - | Personal access token (see fallback order below) |\n\nThe server checks these environment variables in order ā first match wins:\n\n1. `CONFLUENCE_PAT`\n2. `CONFLUENCE_PERSONAL_TOKEN`\n3. `CONFLUENCE_TOKEN`\n\n### Optional settings\n\n| Variable | Default | Description |\n|----------|---------|-------------|\n| `ATLASSIAN_READ_ONLY` | `false` | Set to `true` to globally disable write operations across tools |\n| `JIRA_TIMEOUT` | `30` | HTTP request timeout for Jira in seconds |\n| `JIRA_SSL_VERIFY` | `true` | Set to `false` to skip SSL verification for Jira |\n| `CONFLUENCE_TIMEOUT` | `30` | HTTP request timeout for Confluence in seconds |\n| `CONFLUENCE_SSL_VERIFY` | `true` | Set to `false` to skip SSL verification for Confluence |\n\n## Compatibility\n\n| Client | Supported | Install Method |\n|--------|-----------|----------------|\n| Claude Desktop | Yes | `claude_desktop_config.json` |\n| Claude Code | Yes | `claude mcp add` |\n| Cursor | Yes | One-click deeplink or `.cursor/mcp.json` |\n| Windsurf | Yes | `~/.codeium/windsurf/mcp_config.json` |\n| VS Code Copilot | Yes | `.vscode/mcp.json` |\n| Any MCP client | Yes | stdio or HTTP transport |\n\n## Tools (26)\n\n| Category | Count | Tools |\n|----------|-------|-------|\n| **Jira Issues** | 3 | create (with custom fields), update (with custom fields), create epic |\n| **Jira Links** | 2 | create link, delete link |\n| **Jira Attachments** | 4 | get, upload, download, delete |\n| **Jira Users** | 1 | search by name/email |\n| **Jira Metadata** | 3 | list projects, list fields, backlog |\n| **Jira Agile** | 4 | get board, board config, get sprint, move to sprint |\n| **Jira Versions** | 3 | get project versions, create version, update version |\n| **Confluence Calendars** | 6 | list, search, time-off, who-is-out, person time-off, sprint capacity |\n\n\nFull tool reference (click to expand)
\n\n### Jira Issues\n| Tool | Description |\n|------|-------------|\n| `jira_create_issue` | Create issue with standard and custom fields |\n| `jira_update_issue` | Update issue fields and custom fields |\n| `jira_create_epic` | Create an epic (sets issue type automatically) |\n\n### Jira Links\n| Tool | Description |\n|------|-------------|\n| `jira_create_link` | Create a link between two issues (Relates, Blocks, etc.) |\n| `jira_delete_link` | Delete an issue link by ID |\n\n### Jira Attachments\n| Tool | Description |\n|------|-------------|\n| `jira_get_attachments` | List attachments on an issue |\n| `jira_upload_attachment` | Upload file to issue |\n| `jira_download_attachment` | Download attachment to local file |\n| `jira_delete_attachment` | Delete an attachment |\n\n### Jira Users\n| Tool | Description |\n|------|-------------|\n| `jira_search_users` | Search users by name/email |\n\n### Jira Metadata\n| Tool | Description |\n|------|-------------|\n| `jira_list_projects` | List all accessible projects |\n| `jira_list_fields` | List fields (with search/custom filter) |\n| `jira_backlog` | Get backlog issues for a board |\n\n### Jira Agile\n| Tool | Description |\n|------|-------------|\n| `jira_get_board` | Get board details |\n| `jira_board_config` | Get board column configuration |\n| `jira_get_sprint` | Get sprint details |\n| `jira_move_to_sprint` | Move issues to a sprint |\n\n### Jira Versions\n| Tool | Description |\n|------|-------------|\n| `jira_get_project_versions` | List all versions for a project (REST API v2, Server/DC + Cloud) |\n| `jira_create_version` | Create a new version in a project (REST API v2) |\n| `jira_update_version` | Update an existing version (REST API v2) |\n\n### Confluence Calendars\n| Tool | Description |\n|------|-------------|\n| `confluence_list_calendars` | List all calendars |\n| `confluence_search_calendars` | Search calendars by name/space |\n| `confluence_get_time_off` | Get time-off events for date range |\n| `confluence_who_is_out` | Check who is out on a date |\n| `confluence_get_person_time_off` | Get person's time-off events |\n| `confluence_sprint_capacity` | Calculate sprint capacity with time-off |\n\n \n\n## Resources (15)\n\nThe server exposes curated Jira and Confluence workflow guides as [MCP resources](https://modelcontextprotocol.io/docs/concepts/resources).\n\n| URI | Name | Description |\n|-----|------|-------------|\n| `resource://rules/jira-hierarchy` | Jira Issue Hierarchy | Epic/story/task/subtask relationships, when to use each level |\n| `resource://rules/jira-ticket-writing` | Jira Ticket Writing Standards | Summary format, description structure, acceptance criteria placement |\n| `resource://rules/acceptance-criteria` | Acceptance Criteria Standards | Given/When/Then format, testability, DoD vs AC |\n| `resource://rules/sprint-hygiene` | Sprint Hygiene Rules | Capacity planning, carryover policy, sprint goals, retrospective items |\n| `resource://rules/jira-workflow` | Jira Workflow & Automation | Status transitions, automation triggers, post-functions |\n| `resource://rules/issue-linking` | Issue Linking Best Practices | Link types (blocks, relates, duplicates), cross-project links, epic links |\n| `resource://guides/story-points` | Story Point Estimation | Fibonacci scale, relative sizing, team calibration, anti-patterns |\n| `resource://guides/definition-of-done` | Definition of Done Checklists | Checklist format, team-level vs org-level DoD, verification steps |\n| `resource://guides/jira-labels` | Jira Label Taxonomy | Naming conventions, label categories, label vs component |\n| `resource://guides/jql-library` | JQL Query Library | Common queries, date functions, custom field syntax, saved filters |\n| `resource://guides/custom-fields` | Jira Custom Field Governance | Field types, screen schemes, context, naming standards |\n| `resource://guides/confluence-spaces` | Confluence Space Organization | Space types, permission schemes, archiving, templates |\n| `resource://guides/agile-ceremonies` | Agile Ceremony Standards | Standup, planning, review, retro formats and time-boxing |\n| `resource://guides/git-jira-integration` | Git-Jira Integration Patterns | Smart commits, branch naming, PR linking, status transitions |\n| `resource://templates/confluence-pages` | Confluence Page Templates | ADR, runbook, onboarding, postmortem page structures |\n\n## Prompts (5)\n\nThe server provides [MCP prompts](https://modelcontextprotocol.io/docs/concepts/prompts) ā reusable multi-tool workflow templates that clients can surface as slash commands.\n\n| Prompt | Parameters | Workflow |\n|--------|-----------|----------|\n| `create_ticket` | `project_key`, `issue_type` | Gather fields ā set custom fields (DoD, privacy, security) ā create ā add links |\n| `plan_sprint` | `board_id`, `sprint_id` | Check sprint ā review backlog ā calculate capacity ā suggest scope ā move issues |\n| `close_ticket` | `issue_key` | Verify DoD ā check linked MR ā transition statuses ā add closing comment |\n| `team_availability` | `team_members`, `start_date`, `end_date` | Check who is out ā per-person time-off ā calculate capacity ā flag conflicts |\n| `manage_attachments` | `issue_key` | List attachments ā identify stale/duplicates ā upload/download ā clean up |\n\n## Usage Examples\n\n### Issue Management\n\n```\n\"Create a story in PROJ with custom story points\"\nā jira_create_issue(project_key=\"PROJ\", summary=\"Add OAuth login\", issue_type=\"Story\",\n custom_fields={\"customfield_10004\": 5})\n\n\"Update a ticket's priority and add labels\"\nā jira_update_issue(issue_key=\"PROJ-123\", fields={\"priority\": {\"name\": \"High\"}, \"labels\": [\"urgent\"]})\n\n\"Create an epic and link related stories\"\nā jira_create_epic(project_key=\"PROJ\", epic_name=\"Q1 Auth Overhaul\")\nā jira_create_link(link_type=\"Relates\", inward_issue=\"PROJ-100\", outward_issue=\"PROJ-200\")\n```\n\n### Attachments\n\n```\n\"List attachments on PROJ-123\"\nā jira_get_attachments(issue_key=\"PROJ-123\")\n\n\"Upload a screenshot to a ticket\"\nā jira_upload_attachment(issue_key=\"PROJ-123\", file_path=\"./screenshot.png\")\n\n\"Download an attachment\"\nā jira_download_attachment(content_url=\"https://jira.example.com/rest/api/2/attachment/content/456\",\n save_path=\"./downloads/report.pdf\")\n```\n\n### Agile & Sprint Management\n\n```\n\"Get the current sprint for board 42\"\nā jira_get_board(board_id=42) ā jira_get_sprint(sprint_id=7)\n\n\"Move tickets into the next sprint\"\nā jira_move_to_sprint(sprint_id=8, issue_keys=[\"PROJ-1\", \"PROJ-2\", \"PROJ-3\"])\n\n\"View backlog for board 42\"\nā jira_backlog(board_id=42, max_results=50)\n```\n\n### Version Management\n\n```\n\"List versions for project PROJ\"\nā jira_get_project_versions(project_key=\"PROJ\")\n\n\"Create a new release version\"\nā jira_create_version(project_key=\"PROJ\", name=\"v2.0.0\", release_date=\"2026-04-01\")\n\n\"Mark version as released\"\nā jira_update_version(version_id=\"200\", released=True)\n```\n\n### Time-Off & Sprint Capacity\n\n```\n\"Who is out today?\"\nā confluence_who_is_out(date=\"today\")\n\n\"Get team time-off for the next two weeks\"\nā confluence_get_time_off(start_date=\"today\", end_date=\"+14d\", group_by_person=True)\n\n\"Calculate sprint capacity accounting for PTO\"\nā confluence_sprint_capacity(\n team_members=[\"Alice\", \"Bob\", \"Carol\"],\n sprint_start=\"2025-03-03\", sprint_end=\"2025-03-14\")\n```\n\n## Security Considerations\n\n- **Token scope**: For Jira Cloud, use API tokens scoped to the minimum required permissions. For Data Center, use PATs with project-level access.\n- **Read-only mode**: Set `ATLASSIAN_READ_ONLY=true` to disable all write operations (create, update, delete, upload). Enforced server-side before any API call.\n- **File upload validation**: `jira_upload_attachment` validates file paths (no traversal, max 100MB, file must exist).\n- **Download path restriction**: `jira_download_attachment` only accepts relative paths resolved within the working directory. Absolute paths and path traversal (`../`) are rejected.\n- **Download URL validation**: Attachment download URLs are validated against the configured Jira URL domain to prevent SSRF.\n- **SSL verification**: Enabled by default for both Jira and Confluence. Only disable for self-signed certificates in trusted networks.\n- **MCP tool annotations**: Each tool declares `readOnlyHint`, `destructiveHint`, and `idempotentHint` for client-side permission prompts.\n- **No credential storage**: Tokens are read from environment variables at startup and never persisted.\n\n## Rate Limits & Permissions\n\n### Rate Limits\n\nJira 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.\n\n### Required Permissions\n\n| Operation | Minimum Jira Permission |\n|-----------|----------------------|\n| List projects, fields, boards | Browse Projects |\n| Search users | Browse Users |\n| Create/update issues, epics | Create Issues + Edit Issues |\n| Create/delete issue links | Link Issues |\n| Upload/delete attachments | Create Attachments + Delete Own Attachments |\n| Move issues to sprint | Manage Sprints |\n| Create/update versions | Administer Projects |\n| Confluence calendars/time-off | View space content |\n\n## CLI & Transport Options\n\n```bash\n# Default: stdio transport (for MCP clients)\nuvx mcp-atlassian-extended\n\n# HTTP transport (SSE or streamable-http)\nuvx mcp-atlassian-extended --transport sse --host 127.0.0.1 --port 8000\nuvx mcp-atlassian-extended --transport streamable-http --port 9000\n\n# CLI overrides for config\nuvx mcp-atlassian-extended --jira-url https://jira.example.com --jira-token xxx --read-only\n```\n\nThe server loads `.env` files from the working directory automatically via `python-dotenv`.\n\n**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.\n\n## Related MCP Servers\n\n- [mcp-gitlab](https://github.com/vish288/mcp-gitlab) ā GitLab integration (76 tools, 6 resources, 5 prompts)\n- [mcp-coda](https://github.com/vish288/mcp-coda) ā Coda.io integration (54 tools, 12 resources, 5 prompts)\n\n## Attribution\n\nInspired by [mcp-atlassian](https://github.com/sooperset/mcp-atlassian) by sooperset. Architecture and patterns follow similar conventions.\n\n## Development\n\n```bash\ngit clone https://github.com/vish288/mcp-atlassian-extended.git\ncd mcp-atlassian-extended\nuv sync --all-extras\n\nuv run pytest --cov\nuv run ruff check .\nuv run ruff format --check .\n```\n\n## License\n\nMIT\n",
"bytes": 18649,
"sha": "a98db2de2b6a919ac64f5d8244d54073416ba23657e479393bd4ae59d9b9b5c9",
"repo_slug": "vish288/mcp-atlassian-extended",
"fonte": "repo",
"truncated": false,
"api": "https://agentalog.com/api/listings/mcp_io_github_vish288_mcp_atlassian_extended_710b6b0e/readme"
}