Atlassian Confluence MCP Server

AI を Confluence のナレッジベースに接続する

Claude、Cursor AI、その他の AI アシスタントを Confluence のスペース、ページ、ドキュメントに直接接続して、チームの知識へのアクセス方法や活用方法を変えましょう。ナレッジベースからすぐに回答を得たり、すべてのスペースを横断して検索したり、ドキュメント作成のワークフローを効率化したりできます。

できること

• ドキュメントについて AI に質問する：「API 認証の手順を教えてください」
• すべてのスペースを横断して検索する：「セキュリティのベストプラクティスに関するページをすべて探してください」
• すぐに回答を得る：「Product スペースの最新のリリースノートを表示してください」
• チームの知識にアクセスする：「リモートワークに関する人事ポリシーを教えてください」
• ページのコメントを確認する：「アーキテクチャドキュメントの議論を表示してください」
• コンテンツを作成、更新する：「DEV スペースに新しいページを作成してください」

こんな方に最適

• 技術ドキュメントや API ガイドにすばやくアクセスする必要がある開発者
• 要件、仕様、プロジェクトの更新情報を探すプロダクトマネージャー
• ポリシードキュメントや従業員向けリソースにすばやくアクセスする人事チーム
• トラブルシューティングガイドやナレッジベースの記事を探すサポートチーム
• 自然言語を使って Confluence を操作したいすべての方

クイックスタート

2 分で使い始められます。

1. Confluence の認証情報を取得する

Confluence API トークンを生成します。

1. Atlassian API Tokens にアクセスします
2. Create API token をクリックします
3. 「AI Assistant」 などの名前を付けます
4. 生成されたトークンをすぐにコピーします（再表示されません！）

2. すぐに試す

# Set your credentials
export ATLASSIAN_SITE_NAME="your-company"  # for your-company.atlassian.net
export ATLASSIAN_USER_EMAIL="[email protected]"
export ATLASSIAN_API_TOKEN="your_api_token"

# List your Confluence spaces (TOON format by default)
npx -y @aashari/mcp-server-atlassian-confluence get --path "/wiki/api/v2/spaces"

# Get details about a specific space with field filtering
npx -y @aashari/mcp-server-atlassian-confluence get \
  --path "/wiki/api/v2/spaces/123456" \
  --jq "{id: id, key: key, name: name, type: type}"

# Get a page with JMESPath filtering
npx -y @aashari/mcp-server-atlassian-confluence get \
  --path "/wiki/api/v2/pages/789" \
  --jq "{id: id, title: title, status: status}"

# Search for pages (using CQL)
npx -y @aashari/mcp-server-atlassian-confluence get \
  --path "/wiki/rest/api/search" \
  --query-params '{"cql": "type=page AND space=DEV"}'

AI アシスタントに接続する

Claude Desktop ユーザー向け

Claude の設定ファイル（~/.claude/claude_desktop_config.json）に次の内容を追加します。

{
  "mcpServers": {
    "confluence": {
      "command": "npx",
      "args": ["-y", "@aashari/mcp-server-atlassian-confluence"],
      "env": {
        "ATLASSIAN_SITE_NAME": "your-company",
        "ATLASSIAN_USER_EMAIL": "[email protected]",
        "ATLASSIAN_API_TOKEN": "your_api_token"
      }
    }
  }
}

Claude Desktop を再起動すると、ステータスバーに confluence サーバーが表示されます。

その他の AI アシスタント向け

ほとんどの AI アシスタント（Cursor AI、Continue.dev など）は MCP に対応しています。サーバーをグローバルにインストールします。

npm install -g @aashari/mcp-server-atlassian-confluence

次に、STDIO トランスポートを使用して MCP サーバーに接続するよう、AI アシスタントを設定します。グローバルインストール後は、バイナリを mcp-atlassian-confluence として利用できます。

代替方法：設定ファイル

システム全体の設定には、~/.mcp/configs.json を作成します。

{
  "confluence": {
    "environments": {
      "ATLASSIAN_SITE_NAME": "your-company",
      "ATLASSIAN_USER_EMAIL": "[email protected]",
      "ATLASSIAN_API_TOKEN": "your_api_token"
    }
  }
}

代替の設定キー： "confluence" の代わりに、"atlassian-confluence"、"@aashari/mcp-server-atlassian-confluence"、または "mcp-server-atlassian-confluence" も使用できます。

環境変数を使用する

環境変数または .env ファイルを使って認証情報を設定することもできます。

# Create a .env file in your project directory
cat > .env << EOF
ATLASSIAN_SITE_NAME=your-company
[email protected]
ATLASSIAN_API_TOKEN=your_api_token
DEBUG=false
EOF

サーバーは、次の場所からこれらの値を自動的に読み込みます。

1. 環境変数
2. 現在のディレクトリにある .env ファイル
3. ~/.mcp/configs.json（上記を参照）

利用可能なツール

この MCP サーバーは、Confluence API の任意のエンドポイントにアクセスできる汎用ツールを 5 つ提供します。

ツール	説明
conf_get	任意の Confluence API エンドポイントに GET する（データの読み取り）
conf_post	任意のエンドポイントに POST する（リソースの作成）
conf_put	任意のエンドポイントに PUT する（リソースの置き換え）
conf_patch	任意のエンドポイントに PATCH する（一部の更新）
conf_delete	任意のエンドポイントから DELETE する（リソースの削除）

ツールのパラメーター

すべてのツールで次の共通パラメーターを使用できます。

• path（必須）：API エンドポイントのパス（例：/wiki/api/v2/spaces）
• queryParams（任意）：キーと値のペアで指定するクエリパラメーター（例：{"limit": "25", "space-id": "123"}）
• jq（任意）：レスポンスをフィルタリング、変換する JMESPath 式（例：results[*].{id: id, title: title}）
• outputFormat（任意）：出力形式 — "toon"（デフォルト。トークン数を 30～60％削減）または "json"

リクエストボディを受け取るツール（conf_post、conf_put、conf_patch）：

• body（必須）：JSON オブジェクト形式のリクエストボディ

一般的な API パス

スペース：

• /wiki/api/v2/spaces - すべてのスペースを一覧表示
• /wiki/api/v2/spaces/{id} - スペースの詳細を取得

ページ：

• /wiki/api/v2/pages - ページを一覧表示（space-id クエリパラメーターを使用して絞り込み）
• /wiki/api/v2/pages/{id} - ページの詳細を取得
• /wiki/api/v2/pages/{id}/body - ページ本文を取得（body-format パラメーターを使用）
• /wiki/api/v2/pages/{id}/children - 子ページを取得
• /wiki/api/v2/pages/{id}/labels - ページのラベルを取得

コメント：

• /wiki/api/v2/pages/{id}/footer-comments - フッターコメントを一覧表示／追加
• /wiki/api/v2/pages/{id}/inline-comments - インラインコメントを一覧表示／追加
• /wiki/api/v2/footer-comments/{comment-id} - コメントを取得／更新／削除

ブログ記事：

• /wiki/api/v2/blogposts - ブログ記事を一覧表示
• /wiki/api/v2/blogposts/{id} - ブログ記事を取得

検索：

• /wiki/rest/api/search - コンテンツを検索（cql クエリパラメーターを使用）

TOON 出力形式

TOON とは？ TOON（Token-Oriented Object Notation）は、LLM のトークン効率を最適化した形式で、JSON と比較してトークンコストを 30～60％削減します。すべてのツールでデフォルトの出力形式です。

利点：

• 表形式の配列は JSON 配列より少ないトークン数で済みます
• 構文のオーバーヘッドを最小限に抑えます（不要な引用符、角括弧、カンマを省略）
• それでも人が読みやすく、解析可能です

代わりに JSON を使用する場合：

• 他のツールで標準の JSON が必要な場合
• デバッグや手動での確認が必要な場合

比較例：

// JSON format (verbose)
{"results": [{"id": "123", "title": "My Page"}, {"id": "456", "title": "Other Page"}]}

// TOON format (efficient)
results:
  - id: 123
    title: My Page
  - id: 456
    title: Other Page

TOON の代わりに JSON を使用するには、リクエストで outputFormat: "json" を設定します。

JMESPath によるフィルタリング

すべてのツールで、任意の JMESPath（jq）フィルタリングを使用して特定のデータを抽出し、トークンコストを削減できます。

# Get just space names and keys
npx -y @aashari/mcp-server-atlassian-confluence get \
  --path "/wiki/api/v2/spaces" \
  --jq "results[].{id: id, key: key, name: name}"

# Get page title and status
npx -y @aashari/mcp-server-atlassian-confluence get \
  --path "/wiki/api/v2/pages/123456" \
  --jq "{id: id, title: title, status: status}"

重要： 必要なフィールドだけにレスポンスを絞り込むため、必ず jq パラメーターを使用してください。フィルタリングされていないレスポンスは非常に大きくなり、トークンコストも高くなることがあります。

JMESPath 構文リファレンス：

• 公式ドキュメント：jmespath.org
• よく使われるパターン：
  • results[*] - results 配列内のすべての項目
  • results[0] - 最初の項目のみ
  • results[*].id - すべての項目から ID のみを取得
  • results[*].{id: id, title: title} - 選択したフィールドを持つオブジェクトを作成
  • results[?status=='current'] - 条件で絞り込み

実際の使用例

ナレッジベースを確認する

AI アシスタントに次のように尋ねます：

• 「Confluence のすべてのスペースを一覧表示して」
• 「Engineering スペースの詳細を表示して」
• 「Product スペースにはどのページがある？」
• 「Marketing スペースの最新ページを探して」

情報を検索する

AI アシスタントに次のように尋ねます：

• 「API 認証に関するページを検索して」
• 「タイトルに『security』を含むドキュメントをすべて探して」
• 「『getting-started』のラベルが付いたページを表示して」
• 「DEV スペースでデプロイに関するコンテンツを検索して」

特定のコンテンツにアクセスする

AI アシスタントに次のように尋ねます：

• 「API Authentication Guide ページの内容を取得して」
• 「オンボーディングチェックリストのドキュメントを表示して」
• 「セキュリティポリシーのページには何が書かれている？」
• 「最新のリリースノートを表示して」

コンテンツを作成・更新する

AI アシスタントに次のように尋ねます：

• 「DEV スペースに『API Guide』というタイトルの新しいページを作成して」
• 「アーキテクチャのドキュメントにコメントを追加して」
• 「新しいリリース情報でページの内容を更新して」

CLI コマンド

CLI を使うと、ターミナルから MCP ツールと同等の操作を直接実行できます。すべてのコマンドで、ツールと同じパラメーターを使用できます。

使用可能なコマンド

• get - 任意の Confluence エンドポイントに GET リクエストを送信
• post - 任意のエンドポイントに POST リクエストを送信
• put - 任意のエンドポイントに PUT リクエストを送信
• patch - 任意のエンドポイントに PATCH リクエストを送信
• delete - 任意のエンドポイントから DELETE リクエストを送信

CLI パラメーター

すべてのコマンド：

• -p, --path <path>（必須） - API エンドポイントのパス
• -q, --query-params <json>（任意） - JSON 形式のクエリパラメーター
• --jq <expression>（任意） - JMESPath フィルター式
• -o, --output-format <format>（任意） - 出力形式：toon（デフォルト）または json

リクエストボディを指定するコマンド（post、put、patch）：

• -b, --body <json>（必須） - JSON 形式のリクエストボディ

例

# GET request
npx -y @aashari/mcp-server-atlassian-confluence get --path "/wiki/api/v2/spaces"

# GET with query parameters and JMESPath filter
npx -y @aashari/mcp-server-atlassian-confluence get \
  --path "/wiki/api/v2/pages" \
  --query-params '{"space-id": "123456", "limit": "10"}' \
  --jq "results[*].{id: id, title: title}"

# GET with JSON output format
npx -y @aashari/mcp-server-atlassian-confluence get \
  --path "/wiki/api/v2/spaces" \
  --output-format json

# POST request (create a page)
npx -y @aashari/mcp-server-atlassian-confluence post \
  --path "/wiki/api/v2/pages" \
  --body '{"spaceId": "123456", "status": "current", "title": "New Page", "body": {"representation": "storage", "value": "<p>Content here</p>"}}'

# POST request (add a comment)
npx -y @aashari/mcp-server-atlassian-confluence post \
  --path "/wiki/api/v2/pages/789/footer-comments" \
  --body '{"body": {"representation": "storage", "value": "<p>My comment</p>"}}'

# PUT request (update page - requires version increment)
npx -y @aashari/mcp-server-atlassian-confluence put \
  --path "/wiki/api/v2/pages/789" \
  --body '{"id": "789", "status": "current", "title": "Updated Title", "spaceId": "123456", "body": {"representation": "storage", "value": "<p>Updated content</p>"}, "version": {"number": 2}}'

# PATCH request (partial update)
npx -y @aashari/mcp-server-atlassian-confluence patch \
  --path "/wiki/api/v2/spaces/123456" \
  --body '{"name": "New Space Name"}'

# DELETE request
npx -y @aashari/mcp-server-atlassian-confluence delete \
  --path "/wiki/api/v2/pages/789"

レスポンスの処理

大きなレスポンスの切り捨て

API レスポンスが約 40,000 文字（約 10,000 トークン）を超えると、サーバーはトークン制限内に収めるため、レスポンスを自動的に切り捨てます。この場合：

1. レスポンスの末尾に切り捨て通知が表示されます。通知には次の情報が含まれます：

   • 元のレスポンスのうち、どの程度が表示されているか
   • 元のレスポンスのサイズ
   • 完全なデータにアクセスする方法

2. 完全な生のレスポンスは /tmp/mcp/ 内の一時ファイルに保存されます（パスは切り捨て通知に記載されます）。

3. 切り捨てを避けるためのベストプラクティス：

   • 必要なフィールドだけにレスポンスを絞り込むには、必ず jq パラメーターを使用してください
   • limit クエリパラメーターを使用して、結果数を制限してください（例：{"limit": "5"}）
   • すべてを一覧表示するのではなく、ID を指定して特定のリソースをリクエストしてください
   • 検索には対象を絞った CQL クエリを使用してください

効率的な絞り込みの例：

# Instead of getting all space data (can be huge):
npx -y @aashari/mcp-server-atlassian-confluence get \
  --path "/wiki/api/v2/spaces"

# Get only the fields you need:
npx -y @aashari/mcp-server-atlassian-confluence get \
  --path "/wiki/api/v2/spaces" \
  --query-params '{"limit": "10"}' \
  --jq "results[*].{id: id, key: key, name: name}"

デバッグログ

詳細なリクエスト／レスポンス情報を確認するには、デバッグログを有効にします：

# Set DEBUG environment variable
export DEBUG=true

# For MCP mode
DEBUG=true npx -y @aashari/mcp-server-atlassian-confluence

# For CLI mode
DEBUG=true npx -y @aashari/mcp-server-atlassian-confluence get --path "/wiki/api/v2/spaces"

デバッグログの保存先：~/.mcp/data/@aashari-mcp-server-atlassian-confluence.[session-id].log

テストと開発

MCP Inspector の使用

MCP Inspector は、ツールをテストするためのビジュアルインターフェースを提供します：

# Install the server globally
npm install -g @aashari/mcp-server-atlassian-confluence

# Run with MCP Inspector
npx @modelcontextprotocol/inspector node $(which mcp-atlassian-confluence)

または、リポジトリをクローンしている場合は、組み込みの開発コマンドを使用できます：

npm run mcp:inspect

このコマンドを実行すると、サーバーが HTTP モードで起動し、ブラウザーで Inspector の UI が開きます。

テスト用の HTTP モード

curl やその他の HTTP クライアントでテストするには、サーバーを HTTP モードで実行できます：

# Start server in HTTP mode
TRANSPORT_MODE=http npx -y @aashari/mcp-server-atlassian-confluence

デフォルトでは、サーバーは http://localhost:3000/mcp でリッスンします。ポートは変更できます：

PORT=8080 TRANSPORT_MODE=http npx -y @aashari/mcp-server-atlassian-confluence

curl でのテスト：

# Initialize session
curl -X POST http://localhost:3000/mcp \
  -H "Content-Type: application/json" \
  -H "Accept: application/json, text/event-stream" \
  -d '{"jsonrpc": "2.0", "id": 1, "method": "initialize", "params": {"protocolVersion": "2024-11-05", "clientInfo": {"name": "curl-test", "version": "1.0.0"}, "capabilities": {}}}'

# List available tools
curl -X POST http://localhost:3000/mcp \
  -H "Content-Type: application/json" \
  -H "Accept: application/json, text/event-stream" \
  -d '{"jsonrpc": "2.0", "id": 2, "method": "tools/list"}'

# Call a tool
curl -X POST http://localhost:3000/mcp \
  -H "Content-Type: application/json" \
  -H "Accept: application/json, text/event-stream" \
  -d '{"jsonrpc": "2.0", "id": 3, "method": "tools/call", "params": {"name": "conf_get", "arguments": {"path": "/wiki/api/v2/spaces", "queryParams": {"limit": "5"}}}}'

レスポンスは、次の形式の Server-Sent Events（SSE）として返されます：

event: message
data: {"jsonrpc": "2.0", "id": 1, "result": {...}}

トラブルシューティング

「Authentication failed」または「403 Forbidden」

1. API トークンの権限を確認してください：

   • Atlassian API Tokens にアクセスします
   • トークンが有効で、期限切れになっていないことを確認します

2. サイト名の形式を確認してください：

   • Confluence の URL が https://mycompany.atlassian.net の場合
   • サイト名は mycompany のみです

3. 認証情報をテストしてください：

   npx -y @aashari/mcp-server-atlassian-confluence get --path "/wiki/api/v2/spaces?limit=1"
   

「Resource not found」または「404」

1. API パスを確認してください：

   • パスでは大文字と小文字が区別されます
   • スペースとページにはキーではなく数値 ID を使用してください
   • ブラウザーでリソースが存在することを確認してください

2. アクセス権限を確認してください：

   • ブラウザーでそのスペース／ページにアクセスできることを確認してください
   • 一部のコンテンツは特定のユーザーに制限されている場合があります

検索時に「No results found」と表示される

1. 別の検索語を試してください：

   • 高度な検索には CQL 構文を使用してください
   • 検索条件を広げてみてください

2. CQL 構文を確認してください：

   • まず、Confluence の詳細検索で CQL を検証してください

Claude Desktop との連携に関する問題

1. 設定ファイルを更新した後、Claude Desktop を再起動してください
2. 設定ファイルの場所を確認してください：
   • macOS：~/.claude/claude_desktop_config.json
   • Windows：%APPDATA%\Claude\claude_desktop_config.json

サポートを受ける

問題が解決しない場合：

1. 簡単なテストコマンドを実行して、すべてが動作することを確認します
2. 同様の問題がないか、GitHub Issues を確認します
3. エラーメッセージと設定の詳細を添えて、新しい issue を作成します

よくある質問

必要な権限を教えてください。

Atlassian アカウントには、次の権限が必要です：

• 照会するスペースに対する適切な権限を伴う、Confluence へのアクセス
• 適切な権限を持つ API トークン（作成時に自動的に付与されます）

Confluence Server（オンプレミス）でも使用できますか？

現在、このツールは Confluence Cloud のみをサポートしています。Confluence Server／Data Center のサポートは、今後のバージョンで追加される可能性があります。

サイト名を確認する方法を教えてください。

サイト名は、Confluence URL の最初の部分です：

• URL：https://mycompany.atlassian.net -> サイト名：mycompany
• URL：https://acme-corp.atlassian.net -> サイト名：acme-corp

どの AI アシスタントに対応していますか？

Model Context Protocol（MCP）に対応する AI アシスタントであれば、どれでも利用できます。

• Claude Desktop
• Cursor AI
• Continue.dev
• その他多数

データは安全ですか？

はい。このツールは次のように動作します。

• すべてローカルマシン上で実行されます
• お客様自身の Confluence 認証情報を使用します
• データを第三者に送信することはありません
• アクセス許可を与えた対象にのみアクセスします

すべてのスペースを一度に検索できますか？

はい。スペースをまたいで検索するには、CQL クエリを使用します。例：

npx -y @aashari/mcp-server-atlassian-confluence get \
  --path "/wiki/rest/api/search" \
  --query-params '{"cql": "type=page AND text~\"API documentation\""}'

v2.x からの移行

バージョン 3.0 では、8 個以上の個別ツールが 5 個の汎用 HTTP メソッドツールに置き換えられています。v2.x からアップグレードする場合：

変更前（v2.x）：

conf_ls_spaces, conf_get_space, conf_ls_pages, conf_get_page,
conf_search, conf_ls_comments, conf_add_comment, ...

変更後（v3.0）：

conf_get, conf_post, conf_put, conf_patch, conf_delete

移行例：

• conf_ls_spaces -> パス /wiki/api/v2/spaces を指定した conf_get
• conf_get_space -> パス /wiki/api/v2/spaces/{id} を指定した conf_get
• conf_ls_pages -> パス /wiki/api/v2/pages?space-id={id} を指定した conf_get
• conf_get_page -> パス /wiki/api/v2/pages/{id} を指定した conf_get
• conf_search -> パス /wiki/rest/api/search?cql=... を指定した conf_get
• conf_add_comment -> パス /wiki/api/v2/pages/{id}/footer-comments を指定した conf_post

技術詳細

要件

• Node.js：18.0.0 以降
• MCP SDK：1.23.0（最新の registerTool API を使用）
• Confluence：Cloud のみ（Server／Data Center はサポート対象外）

アーキテクチャ

このサーバーは 5 層アーキテクチャを採用しています。

1. Tools Layer（src/tools/） - Zod による検証を備えた MCP ツール定義
2. CLI Layer（src/cli/） - 直接テストするための Commander ベースの CLI
3. Controllers Layer（src/controllers/） - ビジネスロジック、JMESPath フィルタリング、出力形式の整形
4. Services Layer（src/services/） - Confluence API との通信
5. Utils Layer（src/utils/） - 共有ユーティリティ（ロガー、設定、フォーマッター、TOON エンコーダー）

機能

• 汎用 HTTP メソッドツール - 任意の Confluence API エンドポイントにアクセス
• TOON 出力形式 - JSON と比べてトークンを 30～60% 削減
• JMESPath フィルタリング - 必要なデータのみを抽出
• レスポンスの切り詰め - 大きなレスポンスを自動的に処理
• 生レスポンスのログ記録 - 完全なレスポンスを /tmp/mcp/ に保存
• デュアルトランスポート - STDIO（Claude Desktop 用）と HTTP（ウェブ連携用）
• デバッグログ - トラブルシューティング用の詳細なログ記録

バージョン履歴

v3.2.1（現行）

• API レスポンスが大きい場合に切り詰め処理を行い、生レスポンスをログに記録
• 依存関係の互換性を改善

v3.2.0

• MCP SDK を v1.23.0 に更新し、registerTool API を採用

v3.1.0

• トークン効率に優れた LLM レスポンスを実現する TOON 出力形式を追加

v3.0.0（破壊的変更）

• 8 個以上のドメイン固有ツールを 5 個の汎用 HTTP メソッドツールに置き換え
• JMESPath フィルタリングのサポートを追加
• 汎用メソッドを通じて Confluence API 全体にアクセス可能に

すべてのバージョン履歴については、CHANGELOG.md をご覧ください。

サポート

お困りですか？以下の方法でサポートを受けられます。

1. 上記のトラブルシューティングのセクションをご確認ください - よくある問題のほとんどは、ここで説明しています
2. ドキュメントや例については、GitHub リポジトリをご覧ください：github.com/aashari/mcp-server-atlassian-confluence
3. GitHub Issues で問題を報告してください
4. 機能のリクエストや一般的な質問については、ディスカッションを開始してください

---

ナレッジマネジメントのワークフローに AI を取り入れたいチームのために、心を込めて作りました。