MCP server for Atlassian tools (Confluence, Jira)
  • Python 99.4%
  • Shell 0.5%
Find a file
BartkiewiczM d4ea2b16b5
feat(confluence): add confluence_update_page_section tool for lossless partial page updates (#1141)
* feat(confluence): add confluence_update_page_section tool for lossless partial updates

Adds a new MCP tool and backing PagesMixin method that replaces the content
of a single named section without touching the rest of the page.

The existing update_page flow converts the full page to Markdown and back,
which destroys macros (TOC, Page Properties, Status, etc.), multi-column
layouts, and user mentions. This new tool avoids that entirely:

1. Fetch raw Confluence storage XML (no Markdown conversion).
2. Locate the target section by heading text using BeautifulSoup.
3. Replace only the nodes between that heading and the next same-or-higher
   level heading; everything else — macros, layouts, mentions — is untouched.
4. Write the modified storage XML back with content_representation=storage.

New surface area:
- PagesMixin.update_page_section() in confluence/pages.py
- confluence_update_page_section MCP tool in servers/confluence.py
- 6 unit tests covering section replacement, boundary detection,
  macro preservation, error cases, and format handling

Fixes: lossy full-page Markdown round-trip destroying Confluence macros
Related: #842 (mentions lost), community report on macro loss

* fix(confluence): fix CI failures in update_page_section

- Update hardcoded Confluence tool count from 24 to 25
- Replace BeautifulSoup DOM node-move approach with string-splice
  insertion to avoid PageElement.__copy__ type error flagged by mypy
- Run ruff format on changed files

* style: apply ruff-format to servers/confluence.py and test_pages.py

* docs: document confluence_update_page_section tool

- Add Update Page Section section to confluence-pages.mdx with full
  parameter table, example, tip, and warning about heading matching
- Add confluence_update_page_section to confluence_pages toolset list
  in tools-reference.mdx
- Update tool count from 72 to 73

* refactor(confluence): address self-review findings in update_page_section

- Fix list[Tag] type annotation: NavigableString siblings are also
  collected, so broaden to list to avoid a silent lie + type: ignore
- Remove stale '# 5. (old nodes removed in step 6 below)' comment
- Use heading_text.strip() in 'not found' error to match comparison
- Clarify the heading_pos == -1 guard comment: it is unreachable in
  normal use and indicates a BS4 serialisation edge case, not user error

* test(confluence): verify page section updates

Add server-level and e2e coverage for the Confluence page section update tool, and align tool count documentation with the registered tools.

Github-PR:#1141

---------

Co-authored-by: mcp-maintainer-worker <worker@maintainer.local>
2026-07-06 14:51:51 +09:00
.claude chore: drop invalid allow rules from committed Claude Code settings (#1395) 2026-06-20 13:17:12 +09:00
.devcontainer feat(confluence): add attachment CRUD operations (#898) 2026-02-17 19:12:47 +09:00
.github chore: fix URLs in issue templates (#1105) 2026-07-06 10:20:43 +09:00
docs feat(confluence): add confluence_update_page_section tool for lossless partial page updates (#1141) 2026-07-06 14:51:51 +09:00
helm feat(helm): expose OAuth proxy + client storage configuration for FastMCP auth (#1084) 2026-03-02 23:33:29 +09:00
scripts docs: update documentation for features added since v0.20.0 (#1095) 2026-03-02 13:31:47 +09:00
src/mcp_atlassian feat(confluence): add confluence_update_page_section tool for lossless partial page updates (#1141) 2026-07-06 14:51:51 +09:00
tests feat(confluence): add confluence_update_page_section tool for lossless partial page updates (#1141) 2026-07-06 14:51:51 +09:00
.dockerignore Add version-specific tags for container images on ghcr.io (#293) 2025-04-21 13:00:07 +09:00
.env.example fix(confluence): use v1 REST endpoint for attachment downloads on Cloud (#1369) 2026-07-06 10:26:05 +09:00
.gitignore chore: track CLAUDE.md and .claude/settings.json, add .worktreeinclude (#978) 2026-02-24 18:49:37 +09:00
.mintignore feat(docs): add auto-generated tool reference for all 65 MCP tools (#1017) 2026-02-26 09:45:54 +09:00
.pre-commit-config.yaml ci: pin types-cachetools in the mypy pre-commit hook (#1365) 2026-07-05 21:11:47 +09:00
.worktreeinclude chore: track CLAUDE.md and .claude/settings.json, add .worktreeinclude (#978) 2026-02-24 18:49:37 +09:00
AGENTS.md docs(agents): fix stale Jira/Confluence mixin counts (#1256) 2026-04-10 18:37:07 +09:00
CLAUDE.md chore: track CLAUDE.md and .claude/settings.json, add .worktreeinclude (#978) 2026-02-24 18:49:37 +09:00
CONTRIBUTING.md Feature: update jira_get_issue to honor the project filter (#485) 2025-06-17 01:13:52 +09:00
Dockerfile Upgrade python and dependencies to fix trivy scan issues (#977) 2026-02-24 19:53:18 +09:00
docs.json docs: update documentation for features added since v0.20.0 (#1095) 2026-03-02 13:31:47 +09:00
LICENSE chore: Update copyright holder in LICENSE 2025-05-07 00:50:47 +09:00
pyproject.toml fix(deps): pin fakeredis<2.35.0 to unblock uvx installs (#1250) 2026-04-10 16:29:33 +09:00
README.md feat(confluence): add confluence_update_page_section tool for lossless partial page updates (#1141) 2026-07-06 14:51:51 +09:00
SECURITY.md fix(security): enable private vulnerability reporting and update SECURITY.md 2026-02-20 03:23:51 +09:00
smithery.yaml feat: Add Smithery deployment and installation support (#194) 2025-04-04 00:09:01 +09:00
uv.lock fix(deps): pin fakeredis<2.35.0 to unblock uvx installs (#1250) 2026-04-10 16:29:33 +09:00

MCP Atlassian

PyPI Version PyPI - Downloads PePy - Total Downloads Run Tests License Docs

Model Context Protocol (MCP) server for Atlassian products (Confluence and Jira). Supports both Cloud and Server/Data Center deployments.

https://github.com/user-attachments/assets/35303504-14c6-4ae4-913b-7c25ea511c3e

Confluence Demo

https://github.com/user-attachments/assets/7fe9c488-ad0c-4876-9b54-120b666bb785

Quick Start

1. Get Your API Token

Go to https://id.atlassian.com/manage-profile/security/api-tokens and create a token.

For Server/Data Center, use a Personal Access Token instead. See Authentication.

2. Configure Your IDE

Add to your Claude Desktop or Cursor MCP configuration:

{
  "mcpServers": {
    "mcp-atlassian": {
      "command": "uvx",
      "args": ["mcp-atlassian"],
      "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"
      }
    }
  }
}

Server/Data Center users: Use JIRA_PERSONAL_TOKEN instead of JIRA_USERNAME + JIRA_API_TOKEN. See Authentication for details.

3. Start Using

Ask your AI assistant to:

  • "Find issues assigned to me in PROJ project"
  • "Search Confluence for onboarding docs"
  • "Create a bug ticket for the login issue"
  • "Update the status of PROJ-123 to Done"

Documentation

Full documentation is available at mcp-atlassian.soomiles.com.

Documentation is also available in llms.txt format, which LLMs can consume easily:

Topic Description
Installation uvx, Docker, pip, from source
Authentication API tokens, PAT, OAuth 2.0
Configuration IDE setup, environment variables
HTTP Transport SSE, streamable-http, multi-user
Tools Reference All Jira & Confluence tools
Troubleshooting Common issues & debugging

Compatibility

Product Deployment Support
Confluence Cloud Fully supported
Confluence Server/Data Center Supported (v6.0+)
Jira Cloud Fully supported
Jira Server/Data Center Supported (v8.14+)

Key Tools

Jira Confluence
jira_search - Search with JQL confluence_search - Search with CQL
jira_get_issue - Get issue details confluence_get_page - Get page content
jira_create_issue - Create issues confluence_create_page - Create pages
jira_update_issue - Update issues confluence_update_page - Update pages
jira_transition_issue - Change status confluence_add_comment - Add comments

77 tools total — See Tools Reference for the complete list.

Security

Never share API tokens. Keep .env files secure. See SECURITY.md.

Contributing

See CONTRIBUTING.md for development setup.

License

MIT - See LICENSE. Not an official Atlassian product.