Confluence Mcp Server

confluence-mcp-server

Confluence Cloud／Server／Data Center 向けの MCP サービスです。ページ検索、CQL クエリ、読み取り、作成、更新、添付ファイルのアップロード、ユーザー ID の照会に対応しています。

機能

• confluence_search_pages：キーワードでページを検索
• confluence_execute_cql_search：ネイティブ CQL クエリを実行
• confluence_get_page：ページ ID でコンテンツを取得（storage 形式）
• confluence_get_page_outline：ページの見出し一覧を取得。トークン消費を抑えたナビゲーションに適しています
• confluence_get_page_section：見出しで単一の section を読み取り、ページ全体の本文をモデルに返すことを避けます
• confluence_get_page_anchor_block：Anchor の開始・終了境界でブロックコンテンツを読み取ります
• confluence_create_page：ページを作成（parentId は省略可能）
• confluence_update_page：ページのコンテンツを更新し、バージョンを自動的にインクリメント
• confluence_update_page_section：見出しで単一の section を更新。ページ全体の置換と送信は MCP サーバー側で行います
• confluence_preview_page_section_update：見出しによる更新の該当範囲をプレビューし、旧コンテンツと確認用ハッシュを返します
• confluence_update_page_section_confirmed：ハッシュ確認付きで見出しによる更新を送信し、プレビュー後にコンテンツが変更されていた場合の誤更新を防ぎます
• confluence_add_anchor_block_to_section：見出し section に開始・終了 Anchor を自動追加し、以降の安定した更新を可能にします
• confluence_preview_page_anchor_block_update：Anchor 範囲による更新の該当ブロックをプレビューし、旧コンテンツと確認用ハッシュを返します
• confluence_update_page_anchor_block_confirmed：ハッシュ確認付きで Anchor 範囲による更新を送信します
• confluence_stage_page_update：ページ全体の変更を MCP サーバーのメモリに一時保存し、Confluence には送信しません
• confluence_stage_page_section_update：見出し section の変更を MCP サーバーのメモリに一時保存し、Confluence には送信しません
• confluence_stage_page_anchor_block_update：Anchor ブロックの変更を MCP サーバーのメモリに一時保存し、Confluence には送信しません
• confluence_list_pending_page_updates：現在の MCP プロセスにある未送信の wiki 変更を一覧表示します
• confluence_get_pending_page_update：未送信の変更について、old／new／diff の内容を確認します
• confluence_commit_pending_page_update：ハッシュを検証した後、未送信の変更を Confluence に実際に送信します
• confluence_discard_pending_page_update：未送信の変更を破棄します
• confluence_upload_attachment：ページ添付ファイルをアップロード（ローカルファイルパスまたは base64 に対応。同名の添付ファイルはデフォルトで新しいバージョンに更新）
• confluence_get_current_user：現在の認証ユーザーを取得（whoami）

環境要件

• Node.js 18+
• アクセス可能な Confluence Cloud／Server／Data Center

クイックスタート

npm install
npm run build
npm start

npx での使用（推奨）

npm に公開した後は、リポジトリを手動でクローンせず、MCP クライアントから npx を直接起動できます。

{
  "mcpServers": {
    "confluence": {
      "command": "npx",
      "args": ["-y", "confluence-mcp-server"],
      "env": {
        "CONF_MODE": "server",
        "CONF_BASE_URL": "https://confluence.example.com",
        "CONF_USERNAME": "your-username",
        "CONF_TOKEN": "your-token",
        "CONF_DEFAULT_SPACE": "DOC"
      }
    }
  }
}

クライアント設定に接続情報を記述せず、まず MCP サービスだけを起動することもできます。

{
  "mcpServers": {
    "confluence": {
      "command": "npx",
      "args": ["-y", "confluence-mcp-server"]
    }
  }
}

その後、会話内で接続パラメーターを指定し、モデルに confluence_configure_connection を呼び出させます。

{
  "baseUrl": "https://confluence.example.com",
  "mode": "server",
  "authMode": "auto",
  "username": "your-username",
  "token": "your-token",
  "defaultSpace": "DOC"
}

この設定は現在の MCP サービスプロセスのメモリ内にのみ保存され、再起動すると失われます。継続して使用する場合は、会話のコンテキストに秘密情報が露出しないよう、MCP クライアントの環境変数設定に記述することをおすすめします。

現在のプロセスにすでに接続設定がある場合（環境変数で古いアドレスに接続している場合など）、一部の項目だけを切り替えることもできます。たとえば、アカウントとパスワードはそのままにして、接続先を別の Confluence に切り替える場合は次のようにします。

{
  "baseUrl": "http://192.168.40.82:8090"
}

指定していない mode、認証情報、defaultSpace は現在の接続設定を引き継ぎます。token／password／username／authMode を明示的に指定した場合は、認証情報を再計算します。

環境変数

• CONF_BASE_URL：Confluence のベース URL。例：https://confluence.example.com
• CONF_MODE：デプロイモード。cloud または server（デフォルトは server）
• CONF_AUTH_MODE：認証モード。auto／basic／bearer（デフォルトは auto）
• CONF_USERNAME：ログインユーザー名（Cloud では必須。Server では basic モードの場合、またはパスワードを使用する場合に必須）
• CONF_PASSWORD：ユーザーパスワード（モードに応じて CONF_TOKEN と組み合わせて使用）
• CONF_TOKEN：アクセストークン（Cloud では API Token として使用。Server ではデフォルトで Bearer 認証を使用）
• CONF_DEFAULT_SPACE：デフォルトのスペース Key（省略可能）

これらの環境変数が設定されていない場合、サービスは「接続未設定」の状態で起動します。この場合は、まず confluence_configure_connection を呼び出してください。confluence_get_connection_status で現在の接続状態を確認できます。このツールが token／password を返すことはありません。

MCP クライアント設定例

{
  "mcpServers": {
    "confluence": {
      "command": "node",
      "args": ["dist/index.js"],
      "env": {
        "CONF_MODE": "server",
        "CONF_BASE_URL": "https://confluence.example.com",
        "CONF_USERNAME": "your-username",
        "CONF_TOKEN": "your-token",
        "CONF_DEFAULT_SPACE": "DOC"
      }
    }
  }
}

備考

• このプロジェクトは現在 Confluence の機能に特化しており、Jira ツールは含まれていません。
• Cloud モードでは Basic 認証（CONF_USERNAME + CONF_TOKEN/CONF_PASSWORD）を固定で使用します。
• Server モードでは Bearer または Basic 認証を使用できます（CONF_AUTH_MODE=auto の場合は Bearer が優先されます）。
• Cloud モードの API ベースパスは /wiki/rest/api、Server モードは /rest/api です。
• 画像をアップロードすると、confluence_upload_attachment は storageImageMarkup を返します。これを confluence_update_page の bodyStorageValue に追加すると、画像を表示できます。
• Confluence のネイティブな更新は、引き続きページ全体をバージョン管理して PUT する方式です。confluence_update_page_section は「ページ全体の読み取り + 部分置換 + ページ全体の送信」を MCP サーバー側で行い、モデル側のトークン消費を大幅に削減します。
• 2 段階更新では Confluence 側へのリクエスト回数は減りませんが、誤更新のリスクを大幅に低減できます。プレビューでは旧コンテンツと expectedCurrentHash が返され、確認付き更新ではページを再取得してハッシュが一致することを確認してから送信します。
• 更新を一時保存するツールは、変更を現在の MCP サーバープロセスのメモリ内に保存し、Confluence の PUT は呼び出しません。MCP サービスを再起動すると、未送信の下書きは失われます。
• Anchor モードでは Confluence の Anchor マクロを非表示の境界として使用し、固定領域を長期的に自動管理するのに適しています。通常の閲覧モードでは、これらのアンカーは通常表示されません。

トークン消費を抑えるための推奨フロー

1. まず confluence_search_pages または confluence_execute_cql_search でページを特定します。
2. 次に confluence_get_page_outline で見出し一覧を取得し、ページ全体の本文を直接読み込まないようにします。
3. confluence_get_page_section を使い、heading で必要な section を取得します。
4. 変更後、confluence_update_page_section を使ってその section の storage コンテンツのみを送信します。

ページ内に重複する見出しがある場合は、occurrence で同じ見出しの何番目かを指定できます。matchMode=contains は見出しのあいまい検索に使用できます。

更安全的两阶段更新

1. 先调用 confluence_preview_page_section_update。
2. 检查返回的 oldStorageValue 和 newStorageValue 是否符合预期。
3. 把返回的 expectedCurrentHash 原样传给 confluence_update_page_section_confirmed。
4. 服务端会重新拉取页面并校验 hash，一致才真正提交更新。

未提交改动流程

如果希望 AI 先改 wiki、你检查后再决定是否真正保存，可以使用暂存工具：

1. 用 confluence_stage_page_section_update、confluence_stage_page_anchor_block_update 或 confluence_stage_page_update 创建未提交草稿。
2. 检查返回的 oldStorageValue、newStorageValue、diffStorageValue 和 draftId。
3. 需要稍后查看时，用 confluence_list_pending_page_updates 或 confluence_get_pending_page_update。
4. 确认保存时，用 confluence_commit_pending_page_update 提交；服务端会重新拉取页面并校验 expectedCurrentHash，一致才写入 Confluence。
5. 不想保存时，用 confluence_discard_pending_page_update 丢弃。

这些草稿只存在于当前 MCP 服务端内存，不会出现在 Confluence 页面历史里，也不会跨服务重启持久化。

更稳定的 Anchor 更新

1. 先用 confluence_add_anchor_block_to_section 给目标 section 加上 startAnchor / endAnchor。
2. 后续读取时用 confluence_get_page_anchor_block。
3. 更新时先用 confluence_preview_page_anchor_block_update，确认后再调用 confluence_update_page_anchor_block_confirmed。

Anchor 名称建议使用业务语义化命名，例如 risk-summary-start、risk-summary-end，避免依赖标题文本本身。