Confluence MCP Server

Model Context Protocol (MCP) server for Confluence Cloud search and management. Enables Claude Code to connect to your Confluence instance for searching, reading, and managing documentation with built-in best-practice linting.

Features

Phase 1: Connection Proof ✅

confluence_ping - Test connection and verify authentication
confluence_whoami - Get authenticated user information
confluence_list_spaces - List accessible Confluence spaces

Phase 2: Read & Search ✅

confluence_search - Search using CQL (Confluence Query Language)
confluence_get_page_by_title - Find pages by exact title
confluence_list_pages - List pages in a space
confluence_get_page - Get full page content and metadata
confluence_get_page_metadata - Get metadata without body
confluence_get_children - Get child pages

Phase 3: Safe Write Operations ✅

confluence_create_page - Create new pages (with dry-run)
confluence_update_page - Update existing pages (with dry-run)
confluence_add_labels - Add labels to pages
confluence_remove_labels - Remove labels from pages
confluence_archive_page - Archive pages (with dry-run)

All write operations support dryRun: true for previewing changes.

Phase 4: Best Practices ✅

confluence_lint_page - Check pages for best practice violations
confluence_suggest_improvements - Get actionable improvement suggestions

Checks for:

Title conventions (length, formatting, generic terms)
Missing metadata (owner, last reviewed date)
Content structure (headings, paragraphs, code blocks)
Labels (missing or non-standard)
Staleness (pages not updated in 6+ months)
Excessive nesting depth (4+ levels)

Setup

1. Install Dependencies

cd ~/repos/confluence-mcp-server
npm install

2. Configure Environment

Create a .env file from the template:

cp .env.example .env

Edit .env with your Confluence details:

# Your Confluence Cloud instance
CONFLUENCE_BASE_URL=https://your-domain.atlassian.net

# Your Atlassian account email
CONFLUENCE_EMAIL=your-email@example.com

# API token (generate at https://id.atlassian.com/manage-profile/security/api-tokens)
CONFLUENCE_API_TOKEN=your-api-token-here

# Enable write operations (default: false)
CONFLUENCE_WRITE_ENABLED=false

# Optional: Restrict write operations to specific spaces
# CONFLUENCE_ALLOWED_SPACES=TEAM,DOCS,WIKI

# Optional: Enable audit logging (default: true)
CONFLUENCE_AUDIT_LOG=true

3. Generate Confluence API Token

Go to https://id.atlassian.com/manage-profile/security/api-tokens
Click "Create API token"
Give it a name (e.g., "Claude Code MCP")
Copy the token and paste it into your .env file

4. Add to Claude Code Configuration

Edit ~/.claude.json and add to the global mcpServers section:

{
  "mcpServers": {
    "confluence": {
      "type": "stdio",
      "command": "/Users/joshuamullet/repos/confluence-mcp-server/start-mcp-server.sh",
      "args": [],
      "env": {}
    }
  }
}

Important:

Use the ABSOLUTE path to start-mcp-server.sh
Add to global mcpServers, NOT inside a project's mcpServers
Must include "type": "stdio" field

5. Restart Claude Code

Fully restart Claude Code to load the new MCP server:

# Exit current session
/exit

# Start new session
claude-code

6. Verify Connection

In Claude Code, check that the server is loaded:

/mcp

You should see confluence listed with connection status.

Usage

Connection Test

Test your Confluence connection:

Can you ping the Confluence server and show me the current user?

Claude will call confluence_ping and confluence_whoami to verify connectivity.

Search Examples

Search all spaces: `` Search Confluence for pages about "API documentation" ``

Search specific space: `` Search for pages in the TEAM space that contain "deployment" ``

Advanced CQL: `` Search Confluence using this CQL: type=page AND space=DOCS AND lastModified >= "2025-01-01" ``

Read Examples

Get page by title: `` Get the page titled "Getting Started" from the TEAM space ``

Get page by ID: `` Show me the content of Confluence page 123456 ``

List pages: `` List all pages in the DOCS space ``

Get page tree: `` Show me all child pages of page 123456 ``

Best Practices Linting

Lint a page: `` Lint Confluence page 123456 for best practice issues ``

Get improvement suggestions: `` Suggest improvements for Confluence page 123456 ``

Example output: ``json { "pageId": "123456", "pageTitle": "API Documentation", "totalFindings": 3, "findings": [ { "severity": "warning", "category": "metadata", "message": "Missing owner or contact information", "recommendation": "Add an 'Owner' or 'Contact' section" }, { "severity": "info", "category": "labels", "message": "Page has no labels", "recommendation": "Add labels to improve discoverability" } ] } ``

Write Operations (when enabled)

Important: Write operations require CONFLUENCE_WRITE_ENABLED=true in your .env file.

Create a page: `` Create a new page in the TEAM space titled "New Feature" with this content: <h1>Overview</h1> <p>This is a new feature.</p> ``

Update a page (dry-run first): `` Update page 123456 with a new title "Updated Title" - show me what will change first ``

Add labels: `` Add labels "documentation" and "api" to page 123456 ``

Security

Authentication

Uses Confluence Cloud API tokens (not passwords)
API tokens are stored in .env (gitignored, never committed)
Authentication via HTTP Basic Auth (email + API token)

Write Protection

Write operations disabled by default
Requires explicit CONFLUENCE_WRITE_ENABLED=true
All write operations support dry-run mode
Optional space allowlist restricts modifications

Audit Logging

All tool calls are logged to stderr
Logs include: timestamp, tool name, parameters, success/error
Sensitive data (API tokens) never logged
View logs: tail -f ~/.claude/logs/*.log

Rate Limiting

Automatically detects 429 responses
Returns clear error with retry-after information
Implements basic retry logic with backoff

Troubleshooting

Server not appearing in `/mcp`

Check ~/.claude.json configuration:

Is the server in the global mcpServers section?
Is the path to start-mcp-server.sh absolute and correct?
Is "type": "stdio" present?

Check server starts manually:

   cd ~/repos/confluence-mcp-server
   node mcp-server.js

Should output: Confluence MCP Server running on stdio

Check Claude Code logs:

   tail -f ~/.claude/logs/*.log

Authentication errors

Verify CONFLUENCE_BASE_URL is correct (should be https://your-domain.atlassian.net)
Verify CONFLUENCE_EMAIL matches your Atlassian account
Regenerate API token if needed
Test credentials manually:

  curl -u "your-email:your-token" "https://your-domain.atlassian.net/wiki/rest/api/space"

Write operations disabled

Check CONFLUENCE_WRITE_ENABLED=true in .env
Restart Claude Code after changing .env
Verify the setting loaded: server logs show "Write operations: ENABLED"

Missing environment variables

Error: Missing required environment variables

Solution:

Ensure .env file exists in the server directory
Verify all required variables are set
Check dotenv is loading (see server startup logs)

API Reference

Search with CQL

CQL (Confluence Query Language) examples:

type=page AND space=TEAM
type=page AND title~"API"
type=page AND space=DOCS AND lastModified >= "2025-01-01"
type=page AND label="documentation"
creator=currentUser()

See Confluence CQL documentation for more.

Pagination

Most list operations support pagination:

{
  "limit": 25,    // Results per page (max 100)
  "start": 0      // Offset (0 = first page, 25 = second page, etc.)
}

Dry Run Mode

All write operations support dry-run:

{
  "pageId": "123456",
  "title": "New Title",
  "dryRun": true  // Preview changes without applying
}

Returns what would be changed without making actual modifications.

Development

Project Structure

confluence-mcp-server/
├── mcp-server.js              # Main MCP server (loads dotenv first)
├── start-mcp-server.sh        # Shell wrapper for Claude Code
├── tools/
│   ├── confluence-client.js   # Confluence REST API client
│   └── best-practices.js      # Linting and suggestions
├── package.json
├── .env                       # Your credentials (gitignored)
├── .env.example               # Template
├── .gitignore
└── README.md

Testing Manually

Test individual API calls:

cd ~/repos/confluence-mcp-server
node -e "
import('./tools/confluence-client.js').then(async ({ ConfluenceClient }) => {
  const client = new ConfluenceClient(
    process.env.CONFLUENCE_BASE_URL,
    process.env.CONFLUENCE_EMAIL,
    process.env.CONFLUENCE_API_TOKEN
  );
  const result = await client.ping();
  console.log(result);
});
"

Resources

License

ISC

Confluence MCP Server