MCP Confluence Attachments

MCP汇流附件

模型上下文协议（MCP）服务器和CLI工具，用于从Confluence页面下载图像和draw.io图。

特性

• MCP服务器：将Confluence附件操作作为人工智能助手的MCP工具公开
• CLI工具：用于下载附件的独立命令行界面
• Docker支持：作为容器化应用程序运行
• 柔性运输：支持stdio和HTTP/SSE通信模式
• 智能过滤：仅下载图像、仅下载图表或两者都下载
• 有序存储：自动目录组织（根目录中的图像，子目录中的图表）

安装

本地安装

1. 克隆此存储库：

git clone 
cd mcp-confluence-attachments

1. 创建并激活虚拟环境：

python3 -m venv venv
source venv/bin/activate  # On Windows: venv\Scripts\activate

1. 安装依赖项：

pip install -r requirements.txt

1. 配置环境变量：

cp .env.example .env
# Edit .env with your Confluence credentials

Docker安装

选项1：从Docker Hub拉取（推荐）

拉取预构建的图像：

docker pull quintindk/mcp-confluence-attachments:latest

选项2：本地构建

自己构建Docker镜像：

docker build -t mcp-confluence-attachments .

Claude Code快速入门（推荐）

如果你使用的是Claude Code，你可以用一个命令添加MCP服务器：

claude mcp add confluence-attachments -s user -- sh -c "docker run -i --rm -e MCP_DEBUG=false -v \$(pwd):/output -e LOG_LEVEL=INFO -e MCP_TRANSPORT=stdio -e CONFLUENCE_URL=https://your-instance.atlassian.net -e CONFLUENCE_PERSONAL_TOKEN=\$CONFLUENCE_TOKEN mcp-confluence-attachments"

重要提示：

• 替换 https://your-instance.atlassian.net 使用您的Confluence URL
• 设置 CONFLUENCE_TOKEN 运行此命令之前，请先在shell中设置环境变量：

  export CONFLUENCE_TOKEN="your_personal_access_token"

• 这 -v $(pwd):/output 卷装载可确保下载的文件显示在当前工作目录中
• 这 -s user flag仅为您的用户帐户安装服务器

MCP服务器使用情况

MCP服务器提供了四种使用Confluence附件的工具：

可用工具

1. 列表_附件：在Confluence页面上列出所有附件

- 输入： page_id - 输出：附件元数据列表（ID、标题、媒体类型、文件大小等）

1. 获取附件元数据：获取特定附件的详细元数据

- 输入： page_id, attachment_id - 输出：完整的附件元数据

1. 下载_所有_附件：从页面下载所有（或筛选）附件

- 输入： page_id, output_dir, download_images （布尔）， download_diagrams （布尔） - 输出：下载每个附件的结果

1. 下载_特定_附件：按ID下载单个附件

- 输入： page_id, attachment_id, output_path - 输出：下载状态和文件详细信息

运行MCP服务器

标准模式（用于克劳德桌面/CLI集成）

python confluence_mcp_server.py

或者使用显式环境变量：

CONFLUENCE_URL="https://your-instance.atlassian.net" \
CONFLUENCE_PERSONAL_TOKEN="your_token" \
python confluence_mcp_server.py

HTTP/SSE模式（适用于基于web的客户端）

MCP_TRANSPORT=sse python confluence_mcp_server.py

服务器将在以下时间启动 http://0.0.0.0:8080 与：

• SSE端点： http://0.0.0.0:8080/sse
• 工具列表： http://0.0.0.0:8080/tools

Claude桌面配置（手动方式）

注： 如果您正在使用Claude Code，请使用 claude mcp add 命令显示在上面的快速入门部分，而不是手动编辑配置文件。

对于Claude Desktop，请在配置文件中添加：

• macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
• 视窗: %APPDATA%\Claude\claude_desktop_config.json

使用Docker（推荐）：

{
  "mcpServers": {
    "confluence-attachments": {
      "command": "sh",
      "args": [
        "-c",
        "cd \"$(pwd)\" && docker run -i --rm -v $(pwd):/output -e MCP_TRANSPORT=stdio -e CONFLUENCE_URL=https://your-instance.atlassian.net -e CONFLUENCE_PERSONAL_TOKEN=$CONFLUENCE_TOKEN mcp-confluence-attachments"
      ]
    }
  }
}

设置 CONFLUENCE_TOKEN shell中的环境变量：

export CONFLUENCE_TOKEN="your_personal_access_token"

直接使用Python：

{
  "mcpServers": {
    "confluence-attachments": {
      "command": "python",
      "args": ["/absolute/path/to/confluence_mcp_server.py"],
      "env": {
        "CONFLUENCE_URL": "https://your-instance.atlassian.net",
        "CONFLUENCE_PERSONAL_TOKEN": "your_personal_access_token"
      }
    }
  }
}

环境变量

必需

• CONFLUENCE_URL：Confluence实例的基本URL（例如。， https://your-instance.atlassian.net)
• CONFLUENCE_PERSONAL_TOKEN：用于身份验证的个人访问令牌

可选MCP服务器设置

• MCP_TRANSPORT：通讯方式(stdio, sse，或 http)-默认值： stdio
• MCP_HOST：服务器主机地址-默认值： 0.0.0.0
• MCP_PORT：服务器端口-默认值： 8080
• MCP_DEBUG：启用调试日志记录(true/false)-默认值： false
• MCP_RELOAD：在开发中启用自动重新加载-默认值： false
• LOG_LEVEL：日志记录级别(DEBUG, INFO, WARNING, ERROR, CRITICAL)-默认值： INFO

CLI工具用法

独立CLI工具可以独立于MCP服务器使用：

python download_attachments.py 
 [output_dir]

示例

# Download all attachments to current directory
python download_attachments.py 1142972070

# Download to specific directory
python download_attachments.py 1142972070 ./my-downloads

# View help
python download_attachments.py --help

CLI的环境变量

将这些设置在壳中或 .env 文件：

export CONFLUENCE_URL="https://your-instance.atlassian.net"
export CONFLUENCE_PERSONAL_TOKEN="your_token_here"

Docker使用

Docker容器默认运行MCP服务器，使其易于部署为服务。

运行MCP服务器（带卷装载的标准模式）

对于stdio模式（由Claude Code和Claude Desktop使用），您需要挂载当前目录，以便下载的文件显示在主机上：

docker run -i --rm \
  -v $(pwd):/output \
  -e MCP_TRANSPORT=stdio \
  -e CONFLUENCE_URL="https://your-instance.atlassian.net" \
  -e CONFLUENCE_PERSONAL_TOKEN="your-token-here" \
  mcp-confluence-attachments

为什么卷会增加？

• 没有 -v $(pwd):/output，文件写入容器中，无法在主机上访问
• 挂载使当前目录在以下位置可用 /output 在集装箱内
• 下载的文件将显示在主机上的当前目录中
• 当使用相对路径（例如。， ./downloads)，它们将相对于 /output 在集装箱内

运行MCP服务器（HTTP/SSE模式）

在容器中启动MCP服务器：

docker run --rm \
  -p 8080:8080 \
  -e CONFLUENCE_URL="https://your-instance.atlassian.net" \
  -e CONFLUENCE_PERSONAL_TOKEN="your-token-here" \
  mcp-confluence-attachments

服务器可在以下位置访问：

• SSE端点： http://localhost:8080/sse
• 工具列表： http://localhost:8080/tools

在后台运行

docker run -d \
  --name confluence-mcp \
  -p 8080:8080 \
  -e CONFLUENCE_URL="https://your-instance.atlassian.net" \
  -e CONFLUENCE_PERSONAL_TOKEN="your-token-here" \
  mcp-confluence-attachments

查看日志：

docker logs -f confluence-mcp

停止服务器：

docker stop confluence-mcp

在Docker中使用CLI工具

您还可以通过覆盖入口点来使用CLI工具：

docker run --rm \
  -v $(pwd)/output:/output \
  -e CONFLUENCE_URL="https://your-instance.atlassian.net" \
  -e CONFLUENCE_PERSONAL_TOKEN="your-token-here" \
  --entrypoint python \
  mcp-confluence-attachments download_attachments.py 1142972070 /output

这将创建：

• 图片在 output/ （例如。， output/Site Design.png)
• 在中绘制.io图 output/diagrams/ （例如。， output/diagrams/Site Design.drawio)

Docker环境变量

运行容器时，可以设置所有MCP服务器环境变量：

docker run --rm \
  -p 8080:8080 \
  -e CONFLUENCE_URL="https://your-instance.atlassian.net" \
  -e CONFLUENCE_PERSONAL_TOKEN="your-token" \
  -e MCP_TRANSPORT="sse" \
  -e MCP_PORT="8080" \
  -e MCP_DEBUG="true" \
  -e LOG_LEVEL="DEBUG" \
  mcp-confluence-attachments

下载内容

该工具下载：

• 图像：PNG、JPG、GIF等。（保存到根输出目录）
• Drawing.io图表: .drawio 文件（保存到 diagrams/ 子目录）

它会自动跳过：

• 临时/草稿文件（以开头 ~)
• 媒体类型为“草稿”的文件
• 其他文件类型（Word文档、PDF等）

获取Confluence个人访问令牌

1. 登录您的Confluence实例
2. 点击您的个人资料图片→ 设置
3. 首选 安全 → 个人访问令牌
4. 点击 创建令牌
5. 为其命名并设置过期时间
6. 复制令牌（您将无法再次看到它！）

发展

运行测试

# TODO: Add test instructions once tests are implemented

项目结构

mcp-confluence-attachments/
├── .github/
│   └── workflows/
│       └── docker-publish.yml    # GitHub Actions CI/CD workflow
├── confluence_mcp_server.py      # Main MCP server
├── confluence_client.py          # Confluence API client wrapper
├── config.py                     # Configuration management
├── download_attachments.py       # Standalone CLI tool
├── requirements.txt              # Python dependencies
├── .env.example                  # Environment variable template
├── Dockerfile                    # Docker container definition
├── CICD_SETUP.md                 # CI/CD setup guide
└── README.md                     # This file

故障排除

配置错误

如果你看到 CONFLUENCE_URL environment variable not set:

• 确保你的 .env 文件存在并包含所需变量
• 或者在运行服务器之前将它们导出到shell中

身份验证错误

如果出现401或403错误：

• 验证您的个人访问令牌是否正确且未过期
• 检查您的令牌是否有权访问Confluence页面
• 确保CONFLUENCE_URL与您的实例URL完全匹配

连接错误

如果服务器无法连接到Confluence：

• 验证您的CONFLUENCE_URL是否正确（包括https://）
• 检查您的网络连接和防火墙设置
• 尝试在web浏览器中访问Confluence URL

CI/CD与出版

该项目包括使用GitHub Actions自动构建Docker镜像并发布到Docker Hub。

自动化构建

每一次推 main 自动分支：

• 构建多平台Docker镜像（amd64和arm64）
• 使用以下命令将映像推送到Docker Hub latest 标签
• 更新Docker Hub存储库描述

版本标签（例如。， v1.0.0)自动创建版本图像：

• yourusername/mcp-confluence-attachments:v1.0.0
• yourusername/mcp-confluence-attachments:v1.0
• yourusername/mcp-confluence-attachments:v1

为您的叉子设置CI/CD

如果您分叉此存储库并希望发布到您自己的Docker Hub帐户：

1. 阅读详细的设置指南： CICD_SETUP.md
2. 创建Docker Hub访问令牌
3. 添加 DOCKERHUB_USERNAME 和 DOCKERHUB_TOKEN GitHub存储库的秘密
4. 推到 main 或创建版本标记

工作流文件位于 .github/workflows/docker-publish.yml.

许可证

\[在此处添加您的许可证\]

贡献

欢迎投稿！请打开问题或提交拉取请求。