choipureum/confluence-attachment-mcp-server

Confluence Attachment MCP Server

A Model Context Protocol (MCP) server that enables AI assistants to download and read attachments from Confluence pages.

Features

• 🔍 Page Search: Search Confluence pages by title
• 📄 Page Information: Get page details and attachment count
• 📎 Attachment Management: List and download attachments
• ⬇️ Batch Download: Download all attachments from a page
• 📖 Content Reading: Read and analyze downloaded files
• 📁 File Management: List and manage downloaded files
• 🐳 Docker Optimized: Multi-stage build with Alpine Linux
• 🔧 Modular Architecture: Clean, maintainable code structure
• 🛡️ Security: Non-root user execution
• 📊 Health Checks: Built-in container health monitoring

Quick Start

Prerequisites

• Python 3.11+
• Docker (recommended)
• Confluence API access

Docker Image

• Image Name: confluence-attachment-mcp:latest
• Size: ~183MB (optimized Alpine Linux)
• Base: Python 3.11-alpine
• Architecture: Multi-stage build for optimization

Environment Setup

Create a .env file:

CONFLUENCE_URL=https://your-domain.atlassian.net
CONFLUENCE_USERNAME=your-email@example.com
CONFLUENCE_API_TOKEN=your-api-token
CONFLUENCE_SPACE_KEY=YOUR_SPACE_KEY
MCP_SERVER_NAME=confluence-attachments
MCP_SERVER_VERSION=1.0.0

Docker (Recommended)

# Build and run
./scripts/run.sh

# Or manually
docker build -f config/Dockerfile -t confluence-attachment-mcp:latest .
docker run -d --name confluence-mcp \
  -e CONFLUENCE_URL="https://your-domain.atlassian.net/wiki" \
  -e CONFLUENCE_USERNAME="your-email@example.com" \
  -e CONFLUENCE_API_TOKEN="your-api-token" \
  -e CONFLUENCE_SPACE_KEY="YOUR_SPACE_KEY" \
  -v $(pwd)/downloads:/app/downloads \
  confluence-attachment-mcp:latest

Local Development

# Install dependencies
pip install -r requirements.txt

# Run server
python main.py

MCP Configuration

Cursor Integration

Add to your Cursor MCP configuration:

{
  "mcpServers": {
    "confluence-attachments": {
      "command": "docker",
      "args": [
        "run",
        "-i",
        "--rm",
        "--name",
        "confluence-attachments-mcp",
        "-e",
        "CONFLUENCE_URL",
        "-e",
        "CONFLUENCE_USERNAME",
        "-e",
        "CONFLUENCE_API_TOKEN",
        "-e",
        "CONFLUENCE_SPACE_KEY",
        "-v",
        "${workspaceFolder}/downloads:/app/downloads",
        "confluence-attachment-mcp:latest"
      ],
      "env": {
        "MCP_VERBOSE": "true",
        "CONFLUENCE_URL": "https://your-domain.atlassian.net/wiki",
        "CONFLUENCE_USERNAME": "your-email@example.com",
        "CONFLUENCE_API_TOKEN": "your-api-token-here",
        "CONFLUENCE_SPACE_KEY": "YOUR_SPACE_KEY"
      }
    }
  }
}

Available Tools

Usage Examples

Search for Project Documents

confluence_search_pages_by_title("Project Plan", "DEV")

Download Specific Attachment

confluence_download_attachment("12345", "pdf-test.pdf")

Download All Attachments

confluence_download_all_attachments("12345")

Read File Content

confluence_read_attachment_content("project_plan.pdf")

Project Structure

confluence-attachment-mcp/
├── src/
│   ├── mcp_server/          # MCP server implementation
│   ├── confluence/          # Confluence integration
│   └── utils/               # Utility classes
├── config/                  # Configuration files
├── scripts/                 # Build and deployment scripts
├── docs/                    # Documentation
├── examples/                # Usage examples
├── main.py                  # Entry point
├── requirements.txt         # Python dependencies
├── pyproject.toml          # Project configuration
└── README.md               # This file

Development

Setup Development Environment

# Install development dependencies
pip install -r requirements.txt
pip install -e .

# Run tests
pytest

# Code formatting
black src/
flake8 src/
mypy src/

Building Docker Image

# Build image
docker build -f config/Dockerfile -t confluence-attachment-mcp:latest .

# Run container
docker run -it --rm confluence-attachment-mcp:latest

Contributing

1. Fork the repository
2. Create a feature branch
3. Make your changes
4. Add tests if applicable
5. Submit a pull request

License

This project is licensed under the MIT License - see the file for details.

Support

• Create an issue for bugs or feature requests
• Check the documentation in the docs/ folder
• Review existing issues for solutions

Changelog

v1.0.0

• Initial release
• Basic MCP server functionality
• Confluence attachment management
• Docker support
• Modular code architecture
• Multi-stage Docker optimization
• Security improvements (non-root user)
• Health check implementation
• Enhanced error handling
• File type detection and content reading