Skip to main content
Glama

Confluence Cloud MCP

Confluence Cloud REST API v1 and v2を、Claude Desktopから使えるローカルstdio MCPサーバーとして提供します。検索、ページ本文、Space、階層、添付、コメント、版履歴、主要な更新操作を、LLMが作業の流れに合わせて選べる粒度のToolにまとめています。

認証情報はローカル環境変数、またはClaude Desktop Extensionのsecure configurationから受け取ります。サーバーはstdoutをMCP protocol専用に使うため、診断ログはstderrへ出力します。

Requirements

  • Node.js 20 or newer

  • Confluence Cloud site

  • Atlassian account email

  • Atlassian API token

  • Claude Desktop (stdio configuration or .mcpb Extension)

API tokenはAtlassianのAPI tokens pageで作成します。Confluence CloudのBasic Authは、メールアドレスとAPI tokenを使う方式です。Tokenには必要最小限の権限を持つAtlassianアカウントを使ってください。

Related MCP server: Confluence MCP Server

Quick start with Node

git clone https://github.com/yuu-biz/confluence-cloud-mcp.git
cd confluence-cloud-mcp
npm install
npm run build:bundle

CONFLUENCE_BASE_URL、CONFLUENCE_EMAIL、CONFLUENCE_API_TOKENを設定してサーバーを起動します。PowerShellでは次のように設定できます。

$env:CONFLUENCE_BASE_URL = "https://example.atlassian.net"
$env:CONFLUENCE_EMAIL = "user@example.com"
$env:CONFLUENCE_API_TOKEN = ""
node dist/index.js

.env.exampleをコピーして使う場合も、.envはGitへ追加しないでください。このプロジェクトはdotenvを読み込まないため、Claude Desktopまたは起動環境から環境変数を渡します。

Claude Desktop stdio configuration

Claude Desktopの設定ファイルに、次のエントリを追加します。argsはclone先の絶対パスへ変更し、空のCONFLUENCE_API_TOKENにはローカル設定だけで実際のtokenを入力してください。公開リポジトリの設定例にはtokenを記載しません。

{
  "mcpServers": {
    "confluence-cloud": {
      "command": "node",
      "args": ["C:\\path\\to\\confluence-cloud-mcp\\dist\\index.js"],
      "env": {
        "CONFLUENCE_BASE_URL": "https://example.atlassian.net",
        "CONFLUENCE_EMAIL": "user@example.com",
        "CONFLUENCE_API_TOKEN": "",
        "CONFLUENCE_ALLOW_DESTRUCTIVE_OPERATIONS": "false",
        "CONFLUENCE_ALLOW_RAW_WRITE": "false",
        "CONFLUENCE_ALLOW_LOCAL_FILE_UPLOAD": "false"
      }
    }
  }
}

Claude Desktopを再起動してから、confluence_searchでCQL検索を試してください。

Claude Desktop Extension (.mcpb)

Extensionは、Node.jsを別途用意せずClaude DesktopへローカルMCPサーバーを導入するためのパッケージです。

npm run build:mcpb

生成されたdist/confluence-cloud-mcp.mcpbをClaude Desktopへドラッグするか、Extensionのインストール画面で選択します。設定画面で次を入力します。

  • Confluence site URL: https://example.atlassian.net

  • Atlassian email: user@example.com

  • Atlassian API token: Extensionのsensitive fieldへ入力

  • Destructive operations: 通常は無効

  • Raw write requests: 通常は無効

  • Local file upload: 通常は無効

Extension manifestはMCPB manifest v0.4を使い、API tokenをsensitive: trueのuser configurationから環境変数として渡します。MCPBにはOS-level sandboxがないため、write系の安全制御はサーバー側でも行っています。

High-level Toolを通常優先してください。サーバー内部でpagination、階層再構成、複数API呼び出しを処理するため、Claude DesktopからのTool Callを減らせます。Primitive Toolは、1リソース・1階層だけが必要な場合、cursorを自分で制御したい場合、High-level Toolが公開していないフィールドを使いたい場合に使います。

High-level Tool

集約する処理

confluence_get_content_tree

v2 descendantsのcursor pagination、root取得、階層再構成、budget内でのrender

confluence_search_and_fetch

query→CQL変換、v1 search、上位ページのv2本文取得

confluence_get_page_context

ページ本文・current versionと、指定したancestors / attachments / comments

confluence_get_space_overview

space key解決、Space metadata、homepage/root以下のcontent tree

confluence_get_comment_thread

コメント本体とv2 child commentsのreply tree

Content treeのoutput mode

confluence_get_content_tree(およびconfluence_get_space_overview)は、node objectの羅列ではなくインデント済みテキストを返します。1行 = 1 node、インデント = 階層、末尾の/ = folder、[id]は後続呼び出し用のcontent idです。parentIdやchildPositionは階層から復元できるためcompact outputには含めません。

  • compact(default): output budgetに収まる最も深い表示を返します。収まらない場合はbranchを切り捨てる前にdepthを下げるため、branchは一覧から消えません。

  • outline: 直下の子だけを子数付きで返す「地図」。内部ではdepth 2のdescendantsを1回読むだけで、branchごとのAPI呼び出しは発生しません。巨大・未知の階層はまずこれを取り、必要なbranchだけcompactで展開します。

  • detailed: 従来どおりのnode object。parentId / childPosition / statusが必要なときだけ使います。

Fetched / rendered / omitted と truncation

statusはMCPが取得した量とClaudeへ返した量を分けて報告します。

  • fetchedItems / renderedItems / omittedItems: 取得数、実際にrenderした数、省略された数

  • truncated と truncationReasons: output_budget(renderで省略)、max_items、pagination_limit、api_error

  • omittedBranches: 省略したbranchのid / title / type / fetchedDescendants。関係のありそうなbranchだけroot_idに指定して追加取得できます

  • outputBudget: requestedChars(指定値)、effectiveChars(実際に使われた値)、hardCapChars(サーバー上限50,000)

max_charsは1,000〜50,000の範囲にクランプされます。指定値と実効値が異なる場合もstatus.outputBudgetで確認できます。

truncationReasonsにoutput_budgetが入っている場合、取得済み(fetchedItems)のうちrenderできなかった分なので、max_charsを上げるだけで追加のAPI呼び出しなしに表示を増やせます。compact renderは残り予算で折り畳んだbranchを可能な限り展開するため、予算を上げた分はそのまま表示ノード数に反映されます。

版履歴(Versions of ...)の除外

Confluenceは保持された版を通常の子コンテンツ(Versions of ... フォルダとその配下の版ページ)として持つため、無指定のdescendants取得では版履歴だけでitem budgetを使い切り、兄弟branchに到達できないことがあります。

confluence_get_content_tree と confluence_get_space_overview は既定でこれらを除外します(include_version_history: true で含められます)。除外はpagination中に行われるため、除外されたnodeは max_items を消費しません。除外量は status.excludedVersionHistory(containers / items)で報告するので、黙って消えることはありません。

Primitiveの confluence_list_descendants はAPIの応答をそのまま返す既定(include_version_history: true)のままで、false を指定するとそのページ分だけ同じ規則で除外します(前ページで開いたcontainerは判定できません)。

続きの取得(cursor)

status.nextCursorが返った場合は、同じroot_id / depth / output_modeのままcursorに渡すと続きから取得できます(confluence_get_content_tree、confluence_get_space_overview)。継続ページでは親が前ページに含まれるnodeが出るため、それらはrootの直下に並べ、件数をstatus.unresolvedParentsで報告します(エラー扱いにはしません)。status.cursorUsedには実際に使ったcursorが入ります。

Search mode

confluence_search_and_fetchはCQLを書かずにqueryを渡せます。search_modeはauto(default)で、title = "..."(完全一致)→ title ~ "...*"(前方一致)→ text ~ "..."(全文)の順に試し、最初にhitした時点で止まります。full-text検索はtokenizeされるため、識別子や型番のように正確なtitleが分かっている場合はこの順序が有効です。exact_title / title_prefix / full_textで固定でき、cqlは手書きクエリ用のescape hatchです。実際に使われたCQLはstrategy.cqlUsedに入ります。

Tool overview

Tool

Purpose

confluence_search

CQLでv1検索。IDが不明なときの入口

confluence_list_pages

v2でページ一覧、Space・タイトル・status・cursor検索

confluence_get_page

ページ本文、labels、properties、operations、likes、versions

confluence_get_content

v1の汎用content取得とexpand

confluence_list_spaces / confluence_get_space

Spaceの一覧・詳細

confluence_get_folder / confluence_create_folder

Folderの詳細取得・作成

confluence_list_children

PageまたはFolderの直接の子

confluence_list_descendants

PageまたはFolder以下の子孫とdepth

confluence_get_ancestors

PageまたはFolderの親階層

confluence_list_attachments / confluence_get_attachment

添付ファイルの一覧・メタデータ

confluence_list_comments / confluence_get_comment

footer / inline commentの一覧・詳細

confluence_list_versions / confluence_get_page_version

v2のページ版履歴

confluence_get_content_history

v1の汎用content history

confluence_create_page

Page作成(published / draft、storage / ADF)

confluence_update_page

explicit version number付きPage更新

confluence_update_page_title

titleだけの更新

confluence_create_comment / confluence_update_comment

footer commentの作成・更新

confluence_create_inline_comment / confluence_update_inline_comment

inline commentの作成・更新・resolve

confluence_upload_attachment

opt-inでローカルファイルをPageへアップロード

confluence_delete_page

opt-inでtrash / purge

confluence_raw_request

allowlisted pathだけの未ラップAPIアクセス

典型的な流れは、Space全体の把握には confluence_get_space_overview、ページ検索と本文確認には confluence_search_and_fetch、ページ理解には confluence_get_page_context、階層取得には confluence_get_content_tree(大きい場合はまず output_mode=outline)を使い、1階層だけ必要なときや cursor を自分で制御したいときだけ confluence_list_children などのPrimitiveを使う形です。

Pagination and response size

Primitiveのv2一覧系APIはConfluenceのcursor paginationに合わせ、レスポンスの next_cursor を返します。High-level Toolは、指定budgetに達するまでcursorをMCP内部で消費します。v1 CQL searchは start と next_start を使い、confluence_search_and_fetch は指定した fetch_top だけを本文取得します。 High-level Toolのcursor消費には内部上限(1呼び出しあたり最大20ページ)があり、打ち切った場合は status.truncationReasons に pagination_limit が入ります。

Tool responseはデフォルトで12,000文字に抑え、max_charsで最大50,000文字まで調整できます。ページ本文など大きい値は縮約されるため、必要な本文representationを指定して個別取得してください。

API clientは429と一時的な5xxを指数バックオフとRetry-Afterに従って最大3回再試行します。401、403、404、権限エラーは、statusと安全な説明をTool errorとして返します。Credentials、Authorization header、環境変数値はログやTool responseへ出しません。

Safety controls

デフォルトでは次が無効です。

  • CONFLUENCE_ALLOW_DESTRUCTIVE_OPERATIONS=false: page delete、purge、raw DELETEを無効化

  • CONFLUENCE_ALLOW_RAW_WRITE=false: raw POST / PUT / PATCH / DELETEを無効化

  • CONFLUENCE_ALLOW_LOCAL_FILE_UPLOAD=false: ローカルファイル添付を無効化

有効化しても、破壊的操作・raw write・file uploadはTool inputのconfirm: trueが必要です。raw toolは完全URL、別ホスト、..、query string入りのpathを拒否し、/wiki/api/v2/または/wiki/rest/api/のrelative pathだけを受け付けます。

標準ではCONFLUENCE_BASE_URLをhttps://*.atlassian.netに制限します。管理されたcustom domainを使う場合だけ、CONFLUENCE_ALLOW_CUSTOM_DOMAIN=trueを明示してください。

Development

npm install
npm run check
npm test
npm run build
npm run build:bundle

実Confluence credentialを使わないunit testで、Basic Auth、query encoding、rate-limit retry、API error、pagination、raw path safety、response size boundを検証します。stdioの手動確認には、ビルド後にMCP Inspectorを使えます。

npx @modelcontextprotocol/inspector node dist/index.js

Deliberate limitations

  • OAuth、Atlassian Connect、Forgeの認証は実装していません。ローカル用途のemail + API token Basic Authに限定しています。

  • named toolはPage / Folder階層を中心にし、全REST endpointを1:1では公開していません。未ラップAPIは安全なraw toolで補完します。

  • 添付のダウンロード内容をMCP responseへ埋め込む機能はありません。現状は一覧・メタデータ・opt-in uploadです。

  • Blog post、whiteboard、databaseなどPage以外のcontentは、必要に応じてraw toolまたはv1 confluence_get_contentを使います。

  • ページ更新の競合は自動マージせず、呼び出し側が最新version numberを指定します。

  • Space permission、admin key、永久削除など高権限操作はnamed toolとして追加していません。権限が必要なAPIはraw toolの追加実装と同じpath/method allowlistを通してください。

Official references

License

MIT. See LICENSE.

Available Tools

33 tools
confluence_create_commentC

Create a footer comment on a page or as a reply to an existing comment.

Inputs: body (required), page_id, max_chars, representation, +1 more.

confluence_create_folderB

Create a folder in a Confluence space, optionally under a parent page or folder.

Inputs: title (required), space_id (required), max_chars, parent_id.

confluence_create_inline_commentC

Create an inline comment on a page. inline_comment_properties should contain the selection coordinates required by the Confluence v2 API.

Inputs: body (required), inline_comment_properties (required), page_id, max_chars, +2 more.

confluence_create_pageB

Create a published or draft Confluence page in a space, optionally under a parent page. Body is Confluence storage or Atlas document format.

Inputs: body (required), title (required), space_id (required), status, +4 more.

confluence_delete_pageA

Move a page to the Confluence trash, or permanently purge a trashed page. Disabled unless CONFLUENCE_ALLOW_DESTRUCTIVE_OPERATIONS=true and confirm=true.

Inputs: confirm (required), page_id (required), draft, purge, +1 more.

confluence_get_ancestorsA

Primitive: get the ancestor chain for a page or folder. When the surrounding page context is also needed, prefer confluence_get_page_context.

Inputs: content_id (required), max_chars, content_type.

confluence_get_attachmentB

Get attachment metadata and optional version, labels, properties, operations, or collaborators.

Inputs: attachment_id (required), version, max_chars, include_labels, +4 more.

confluence_get_commentA

Primitive: get one footer or inline comment by ID. For the comment plus its bounded reply tree, prefer confluence_get_comment_thread.

Inputs: comment_id (required), version, max_chars, body_format, +2 more.

confluence_get_comment_threadA

HIGH-LEVEL: Get one footer or inline comment plus its reply tree in one MCP call. Prefer this over repeatedly calling confluence_get_comment and child-comment endpoints. max_depth and max_items bound recursive traversal; partial/truncated status is explicit.

Inputs: comment_id (required), max_chars, max_depth, max_items, +2 more.

confluence_get_contentA

Get a generic Confluence content item through REST API v1 when v2 does not expose the needed content shape or expansion.

Inputs: content_id (required), expand, max_chars.

confluence_get_content_historyB

Get v1 history details for generic Confluence content, useful when the v2 page model does not expose the required history shape.

Inputs: content_id (required), limit, start, expand, +1 more.

confluence_get_content_treeA

HIGH-LEVEL: Get a page or folder hierarchy in one MCP call, rendered as an indented text tree (title [id], a trailing / marks folders). Prefer this over recursively calling confluence_list_children: the server reads v2 descendants, consumes cursor pagination, and rebuilds the hierarchy. output_mode=compact (default) returns the deepest view that fits the output budget and lists collapsed branches in omittedBranches, so a follow-up call can expand only what matters; output_mode=outline returns just the direct children with child counts and is the cheapest way to map a large or unknown tree first; output_mode=detailed returns raw node objects and is only worth it when parentId, childPosition or status are needed. Retained document versions, which Confluence stores as "Versions of ..." child content, are excluded by default so history cannot consume the item budget ahead of sibling branches; set include_version_history=true to include them, and status.excludedVersionHistory reports what was skipped. status separates fetchedItems from renderedItems and names every truncationReason. When status.nextCursor is returned, pass it back as cursor with the same root_id, depth and output_mode to continue the traversal; when truncationReasons contains output_budget, raising max_chars renders more of what was already fetched without extra API calls.

Inputs: root_id (required), depth, cursor, max_chars, +4 more.

confluence_get_folderA

Get one Confluence folder by ID, optionally including direct children, operations, properties, or collaborators.

Inputs: folder_id (required), max_chars, include_operations, include_properties, +2 more.

confluence_get_pageA

Primitive: get one Confluence page by ID. Use it when a single page body or a specific field set is all that is needed. For the page plus its ancestors, attachments, or comments, prefer confluence_get_page_context.

Inputs: page_id (required), status, version, max_chars, +6 more.

confluence_get_page_contextA

HIGH-LEVEL: Gather the information commonly needed to understand one page in one MCP call: body/current version plus optional ancestors, attachments, and comments. Prefer this over calling several page context primitives separately; optional section failures are returned with partial status.

Inputs: page_id (required), max_chars, body_format, comment_types, +4 more.

confluence_get_page_versionC

Get details for one historical page version.

Inputs: page_id (required), version_number (required), max_chars.

confluence_get_spaceA

Primitive: get one Confluence space by ID when only the space record is needed. When first understanding a space and its structure, prefer confluence_get_space_overview, which also accepts a space key.

Inputs: space_id (required), max_chars, include_icon, description_format, +3 more.

confluence_get_space_overviewA

HIGH-LEVEL: Get space metadata and the homepage/root content tree in one MCP call. Prefer this when first learning a space instead of listing spaces, fetching the space, and recursively listing children. Provide either space_id or space_key; with space_key (for example DOCS) the server resolves the numeric space id itself. status.nextCursor can be passed back as cursor to continue the tree traversal. The tree is always budgeted and reports partial/truncated state.

Inputs: depth, cursor, root_id, space_id, +6 more.

confluence_list_attachmentsA

Primitive: list attachments for a page with optional filename, media type, status, and cursor filters. For attachments together with the page body and comments, prefer confluence_get_page_context.

Inputs: page_id (required), limit, cursor, status, +3 more.

confluence_list_childrenA

Primitive: list one direct level of page or folder children. Use it when exactly one immediate level is needed, or when the caller wants to drive cursor pagination itself. For recursive hierarchy exploration prefer confluence_get_content_tree; for a large or unknown hierarchy call it with output_mode=outline first and expand only the branches that matter.

Inputs: parent_id (required), sort, limit, cursor, +2 more.

confluence_list_commentsA

Primitive: list root footer or inline comments on a page. For one discussion and all bounded replies, prefer confluence_get_comment_thread; use this for a single page-level comment list.

Inputs: page_id (required), sort, limit, cursor, +5 more.

confluence_list_descendantsA

Primitive: list one paginated descendants response below a page or folder, in flat top-to-bottom order. Returns the API response as-is, including the "Versions of ..." containers Confluence uses for retained document versions; set include_version_history=false to drop those and everything under them from this page of results. Use it when a raw page of descendants or manual cursor control is needed. For a rendered hierarchy with pagination handled server-side, and with version history excluded by default, prefer confluence_get_content_tree.

Inputs: parent_id (required), depth, limit, cursor, +3 more.

confluence_list_pagesC

List Confluence pages with optional space, title, status, ID, and body format filters. Use cursor from the previous response for the next page.

Inputs: ids, sort, limit, title, +5 more.

confluence_list_spacesC

List Confluence spaces with optional key, type, status, and description format filters.

Inputs: keys, sort, type, limit, +4 more.

confluence_list_versionsB

List page version history with optional body representation and cursor pagination.

Inputs: page_id (required), sort, limit, cursor, +2 more.

confluence_raw_requestA

Call an allowlisted Confluence REST API path for an operation not covered by a named tool. Path must be under /wiki/api/v2/ or /wiki/rest/api/. GET is enabled by default; non-GET requires CONFLUENCE_ALLOW_RAW_WRITE=true and confirm=true, and DELETE also requires destructive opt-in.

Inputs: path (required), method (required), body, query, +2 more.

confluence_search_and_fetchA

HIGH-LEVEL: Find pages and read their bodies in one MCP call. Prefer this over confluence_search followed by confluence_get_page per result. Pass a plain query with search_mode instead of writing CQL: auto (default) tries exact title, then title prefix, then full text and stops at the first mode that matches, which keeps identifiers such as codes or part numbers from being diluted by full-text tokenization; exact_title, title_prefix and full_text pin one strategy; cql is the escape hatch for a hand-written query. strategy.cqlUsed reports what actually ran. Non-page or failed fetches come back as partial results.

Inputs: cql, query, start, fetch_top, +6 more.

confluence_update_commentA

Update a footer comment body. Use confluence_get_comment first if you need to inspect its current version.

Inputs: body (required), comment_id (required), max_chars, representation.

confluence_update_inline_commentC

Update or resolve an inline comment.

Inputs: comment_id (required), body, resolved, max_chars, +1 more.

confluence_update_pageA

Update a page body and title using an explicit current version number. Read the page first when unsure; Confluence requires optimistic versioning.

Inputs: body (required), title (required), page_id (required), version_number (required), +7 more.

confluence_update_page_titleC

Update only a page title using the v2 title endpoint and explicit version number.

Inputs: title (required), page_id (required), version_number (required), max_chars, +2 more.

confluence_upload_attachmentA

Upload a local file to a page using REST API v1. Disabled unless CONFLUENCE_ALLOW_LOCAL_FILE_UPLOAD=true and confirm=true; the file path is read by this local process.

Inputs: confirm (required), page_id (required), file_path (required), comment, +1 more.

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    TDQS

    B3.3/5.0

    Scored across 33 tools

    Disambiguation5/5

    All 33 tools have clearly defined, non-overlapping purposes. High-level composite tools (e.g., confluence_get_content_tree, confluence_search_and_fetch) are explicitly distinguished from the primitives they wrap (e.g., confluence_list_children, confluence_search), with guidance on when to prefer each. No two tools appear to do the same thing.

    Naming Consistency5/5

    Every tool follows the same `confluence_` prefix plus a verb_noun convention (e.g., list_pages, get_page, create_page, update_page, delete_page, upload_attachment). Even composite tools like get_content_tree and get_space_overview fit the pattern with descriptive nouns. No mixed camelCase or inconsistent verbs observed.

    Tool Count2/5

    With 33 tools, this server exceeds the 25+ threshold that signals an overly heavy tool surface. While each tool is individually useful, the large number increases the risk of agent confusion and selection fatigue. A few composite tools absorb some redundancy, but the overall count is still high for a typical MCP server.

    Completeness4/5

    The tool surface covers core Confluence operations thoroughly: page and comment CRUD, folder management, attachments, version history, search, and content tree traversal. Minor gaps exist (e.g., no explicit move/copy page, no label management), but the raw_request escape hatch mitigates these, so the set is nearly complete for common workflows.

    Maintenance

    ActivityStale
    ResponsivenessNo recent community issues

    Related MCP Connectors

    Related MCP Servers