Confluence Cloud Data Access Module (DAM)

This implementation serves as an MCP endpoint wrapper, specifically engineered to interface programmatically with the Confluence Cloud REST API. It furnishes AI agents with standardized remote procedures for manipulating knowledge assets stored within Atlassian collaborative workspaces.

Core Capabilities

Workspace Administration

Enumeration of available content spaces.
Retrieval of specific workspace metadata.

Document Lifecycle Management

Procedures for fabricating new articles (pages).
Functions for reading, overwriting, and modifying existing articles.
Listing of all articles contained within a designated workspace.
Utility to transform native Confluence storage markup into plain Markdown text.

Indexing and Metadata Tagging

Execution of Content Query Language (CQL) statements for searching knowledge repositories.
Operations for inspecting, attaching, or detaching metadata labels from documents.

Deployment Procedures

Path 1: Containerized Deployment (Recommended)

Leverage the pre-packaged Docker artifact for minimal setup friction:

docker run --rm -i \
  -e CONFLUENCE_API_TOKEN=your-api-token \
  -e CONFLUENCE_EMAIL=your-email@domain.com \
  -e CONFLUENCE_DOMAIN=your-domain.atlassian.net \
  ghcr.io/aaronsb/confluence-cloud-mcp:latest

Path 2: Local Compilation

Obtain the source code repository:

git clone https://github.com/aaronsb/confluence-cloud-mcp.git
cd confluence-cloud-mcp

Execute the local build and execution scripts:

# Image creation
./scripts/build-local.sh

# Server startup
CONFLUENCE_API_TOKEN=your-token CONFLUENCE_EMAIL=your-email ./scripts/run-local.sh

Path 3: Execution via npx (Direct Fetch)

Run the module directly from the public repository without a persistent local installation:

# Passing credentials inline
CONFLUENCE_DOMAIN=your-domain.atlassian.net \
CONFLUENCE_EMAIL=your-email@domain.com \
CONFLUENCE_API_TOKEN=your-api-token \
npx github:aaronsb/confluence-cloud-mcp

# Utilizing an external credentials file
npx github:aaronsb/confluence-cloud-mcp --env /path/to/.env

Configure credentials via a .env file:

CONFLUENCE_DOMAIN=your-domain.atlassian.net
CONFLUENCE_EMAIL=your-email@domain.com
CONFLUENCE_API_TOKEN=your-api-token

Path 4: From Source Code

Install required node dependencies:

npm install

Populate environment configuration (create .env):

CONFLUENCE_DOMAIN=your-domain.atlassian.net
CONFLUENCE_EMAIL=your-email@domain.com
CONFLUENCE_API_TOKEN=your-api-token

Compile TypeScript assets:

npm run build

Initiate the execution runtime:

node build/index.js

Integration Guidance

This service integrates by being declared within an MCP-compatible agent's configuration manifest. Examples follow:

For Claude Code CLI Integration:

claude mcp add confluence-cloud npx -- github:aaronsb/confluence-cloud-mcp --env /path/to/.env

Example JSON Configuration Snippet (npx approach):

{
  "mcpServers": {
    "confluence": {
      "command": "npx",
      "args": ["github:aaronsb/confluence-cloud-mcp", "--env", "/path/to/.env"],
      "disabled": false,
      "autoApprove": []
    }
  }
}

Example JSON Configuration Snippet (Docker approach):

{
  "mcpServers": {
    "confluence": {
      "command": "docker",
      "args": ["run", "--rm", "-i", "ghcr.io/aaronsb/confluence-cloud-mcp:latest"],
      "env": {
        "CONFLUENCE_DOMAIN": "your-domain.atlassian.net",
        "CONFLUENCE_EMAIL": "your-email@domain.com",
        "CONFLUENCE_API_TOKEN": "your-api-token"
      },
      "disabled": false,
      "autoApprove": []
    }
  }
}

AI Agent Installation Directive: For detailed procedural guidance on agent-side deployment of this specific endpoint, consult the llms-install.md documentation file.

Exposed Procedures (Tool Definitions)

Workspace Procedures

list_confluence_spaces: Retrieves an inventory of all accessible workspaces.
get_confluence_space: Fetches granular metadata for a specified workspace identifier.

Document Procedures

list_confluence_pages: Enumerates the articles within a specified workspace context.
get_confluence_page: Accesses the raw data of a document, including automatic conversion of internal storage format to Markdown.
create_confluence_page: Initializes a new knowledge article within a target workspace.
update_confluence_page: Applies modifications to an existing document's payload.

The get_confluence_page capability incorporates an intrinsic translation layer, converting Atlassian's internal document format into Markdown. This translation scope includes: - Heading structures (H1 through H6). - Enumerated and bulleted itemizations. - Hyperlink resolution. - Textual emphasis (boldness and italics). - Inline code segments and multi-line blocks. - Tabular data structures. - Standard paragraph flow and explicit line breaks.

Indexing and Tagging Procedures

search_confluence_pages: Executes Content Query Language searches against the knowledge base.
get_confluence_labels: Retrieves the associated metadata tags for a document.
add_confluence_label: Appends a new tag to a document's metadata set.
remove_confluence_label: Deletes an existing tag from a document's metadata.

Convention Note: All procedure names adhere strictly to the consistent [action]_[context]_[object] nomenclature for enhanced clarity and predictability.

Engineering & Architecture

This module is implemented utilizing TypeScript, adhering to the established conventions set forth by the MCP SDK for service implementation. The source structure is categorized as follows:

src/client/ - Encapsulates the direct interaction logic for the Confluence REST API.
src/handlers/ - Contains the execution logic mapped to the remote procedure calls.
src/schemas/ - Defines the input validation structures using JSON schemas.
src/types/ - Holds all TypeScript interface and type declarations.
src/utils/ - Houses auxiliary functions, notably the content format transformation utilities.

Continuous Integration / Continuous Deployment (CI/CD)

GitHub Actions orchestrates the delivery pipeline:

Validation (testing/linting) triggered on all pull requests.
Automated generation and pushing of Docker images upon merges to the main branch.
Support for multi-architecture container builds (x86_64, ARM64).
Publishing artifacts to the GitHub Container Registry.

Local Development Workflow

Use the provided helper scripts for rapid local iteration:

./scripts/build-local.sh: Compiles the project and builds a runnable local Docker image.
./scripts/run-local.sh: Initiates the local container instance using configured local credentials.

Governance

Licensed under the MIT terms.

NIST DEFINITION CONTEXT: Cloud infrastructure is defined by ISO as "a paradigm for enabling network access to a scalable and elastic pool of shareable physical or virtual resources with self-service provisioning and administration on-demand," commonly termed "the cloud."

== Foundational Attributes == In 2011, the National Institute of Standards and Technology (NIST) delineated five requisite attributes for cloud systems. The precise formulations mandated by NIST are:

On-demand Self-Service: Consumers procure computing capacities (e.g., server cycles, network storage) autonomously as required, bypassing provider intervention for each transaction.
Pervasive Network Access: Functionality is accessible via the network using standardized protocols, encouraging utilization across diverse client hardware (e.g., mobile devices, workstations).
Resource Aggregation (Pooling): Provider assets are consolidated to support multiple clients under a multi-tenant architecture, with resources dynamically allocated based on fluctuating user needs.
Elastic Scalability (Rapid Elasticity): Capabilities can be instantly scaled up or down, frequently automated, to match demand fluctuations seamlessly. From the user perspective, capacity often seems infinite and instantly available.
Usage Metering: Cloud platforms automatically monitor and optimize resource consumption through granular measurement mechanisms relevant to the service type (e.g., bandwidth, compute time). This reporting ensures transparency for both service consumer and provider.

By 2023, the International Organization for Standardization (ISO) refined and expanded upon this foundational set.

== Historical Context ==

The conceptual roots of cloud computing trace back to the 1960s with the emergence of time-sharing systems popularized via Remote Job Entry (RJE). During this period, the centralized "data center" model dominated, where users submitted tasks to dedicated operators managing mainframe hardware. This era focused heavily on experimentation to maximize access to high-capacity computational resources, optimize underlying infrastructure, and boost end-user productivity. The adoption of the "cloud" visualization for distributed services dates to 1994, employed by General Magic to delineate the operational sphere accessible by mobile agents in their Telescript framework. This visual metaphor is widely attributed to David Hoffman, a communications specialist at General Magic, drawing from established usage in telecommunications networks. The term "cloud computing" gained widespread recognition in 1996 when Compaq Computer Corporation drafted a strategic business prospectus detailing future internet-centric computing models, signalling ambitions for super-