Confluence MCP Server

Model Context Protocol (MCP) server for integrating Confluence with AI agents. This server allows AI assistants to search, read, and retrieve documentation from your Confluence workspace.

Features

• 🔍 Search Confluence - Full-text and CQL search across spaces
• 📄 Get Page by ID - Retrieve complete page content by ID
• 📝 Get Page by Title - Find pages by exact title match
• 📚 List Space Pages - Get all pages in a space
• 🌲 Get Page Children - Navigate page hierarchies
• 📥 Sync Docs - Sync Confluence pages to local markdown files
• 📤 Push MD to Confluence - Push markdown files to Confluence (create/update pages)

Installation

git clone https://github.com/harshpuri84/confluence-mcp.git
cd confluence-mcp
npm install
npm run build

Configuration

1. Create a .env file from the example:

cp .env.example .env

2. Configure your Confluence credentials:

CONFLUENCE_BASE_URL=https://your-domain.atlassian.net
CONFLUENCE_USER_EMAIL=your-email@example.com
CONFLUENCE_API_TOKEN=your-api-token
CONFLUENCE_SPACE_KEY=DOCS
CONFLUENCE_PAGE_LIMIT=10
CONFLUENCE_SYNC_DIR=./confluence-docs

Getting Confluence API Token

1. Go to https://id.atlassian.com/manage-profile/security/api-tokens
2. Click "Create API token"
3. Give it a descriptive name (e.g., "MCP Server")
4. Copy the token and add it to your .env file

Usage with Claude Desktop

Add to your Claude Desktop configuration (~/Library/Application Support/Claude/claude_desktop_config.json on macOS):

{
  "mcpServers": {
    "confluence": {
      "command": "node",
      "args": [
        "/Users/harsh.puri/Documents/AI-airlcl/mcp-servers/confluence-mcp/dist/index.js"
      ],
      "env": {
        "CONFLUENCE_BASE_URL": "https://your-domain.atlassian.net",
        "CONFLUENCE_USER_EMAIL": "your-email@example.com",
        "CONFLUENCE_API_TOKEN": "your-api-token",
        "CONFLUENCE_SPACE_KEY": "DOCS"
      }
    }
  }
}

Restart Claude Desktop after configuration.

Available Tools

search_confluence

Search Confluence for pages matching a query.

Parameters:

• query (required): Search query or CQL statement
• limit (optional): Maximum results (default: 10)
• spaceKey (optional): Restrict to specific space

Example queries:

"freight operations"
"text ~ \"booking\" AND space = DOCS"
"title ~ \"API\" AND type = page"

get_page_by_id

Get a Confluence page by its ID.

Parameters:

• pageId (required): The page ID
• expandBody (optional): Include content (default: true)

get_page_by_title

Find a page by exact title match.

Parameters:

• title (required): Exact page title
• spaceKey (required): Space key

get_space_pages

List all pages in a space.

Parameters:

• spaceKey (required): The space key
• limit (optional): Max pages (default: 25)

get_page_children

Get child pages of a parent page.

Parameters:

• pageId (required): Parent page ID
• limit (optional): Max children (default: 25)

sync_confluence_docs

Sync Confluence pages to local markdown files. Supports syncing entire spaces, search results, or specific pages.

Parameters:

• spaceKey (optional): Space key to sync all pages from
• query (optional): CQL query to sync matching pages
• pageIds (optional): Array of specific page IDs to sync
• outputDir (optional): Output directory (default: ./confluence-docs)
• includeChildren (optional): Include child pages (default: false)
• recursive (optional): Recursively sync child pages (default: false)

Note: You must provide at least one of spaceKey, query, or pageIds.

Syncing Docs to Local Files

Using the Standalone Sync Script

The Confluence MCP includes a standalone CLI script for syncing documentation:

# Build the project first
npm run build

# Sync all pages from a space
node dist/sync.js space DOCS

# Sync to a custom directory
node dist/sync.js space DOCS ./my-docs

# Sync recursively (includes all child pages)
node dist/sync.js space DOCS --recursive

# Sync pages matching a query
node dist/sync.js query "API documentation"

# Sync with space filter
node dist/sync.js query "best practices" --space DOCS

# Sync specific pages by ID
node dist/sync.js pages 123456 789012 345678

Using the MCP Tool

You can also sync docs via the MCP sync_confluence_docs tool:

{
  "tool": "sync_confluence_docs",
  "arguments": {
    "spaceKey": "DOCS",
    "outputDir": "./confluence-docs",
    "recursive": true
  }
}

Output Format

Synced files are saved as Markdown with frontmatter:

• Files are organized by space key: {outputDir}/{spaceKey}/{page-title}.md
• Each file includes metadata (ID, title, space, URL, version, last modified)
• HTML content is converted to Markdown
• Child pages are included if recursive or includeChildren is true

Example output structure:

confluence-docs/
  DOCS/
    Getting-Started.md
    API-Reference.md
    Best-Practices.md
    Sub-Page.md

Pushing Markdown Files to Confluence

Using the Standalone Push Script

Push markdown files to Confluence using the CLI script:

# Build the project first
npm run build

# Push a single markdown file
node dist/push.js file document.md --space DOCS

# Push with parent page (create as child page)
node dist/push.js file document.md --space DOCS --parent 123456

# Push all markdown files from a directory
node dist/push.js dir ./docs --space DOCS

# Push directory with parent page
node dist/push.js dir ./docs --space DOCS --parent 123456

# Create new pages only (don't update existing)
node dist/push.js file document.md --space DOCS --no-update

# Or use npm script
npm run push file document.md --space DOCS

Using the MCP Tool

You can also push markdown files via the MCP push_md_to_confluence tool:

{
  "tool": "push_md_to_confluence",
  "arguments": {
    "filePath": "./document.md",
    "spaceKey": "DOCS",
    "updateExisting": true
  }
}

Or push an entire directory:

{
  "tool": "push_md_to_confluence",
  "arguments": {
    "directory": "./docs",
    "spaceKey": "DOCS",
    "parentPageId": "123456"
  }
}

File Format

Markdown files can include frontmatter for metadata:

---
id: 123456
title: My Document Title
spaceKey: DOCS
---

# My Document

Content goes here...

Frontmatter fields:

• id (optional): Existing Confluence page ID - if provided, will update that page
• title (optional): Page title - defaults to filename if not provided
• spaceKey (optional): Space key - can be provided via CLI/API parameter instead

Behavior:

• If id is in frontmatter and page exists → Updates the page
• If title matches existing page in space → Updates the page (if updateExisting is true)
• Otherwise → Creates a new page
• Markdown is converted to HTML automatically
• Supports standard markdown: headings, lists, code blocks, links, etc.

Example AI Prompts

Once configured, you can ask Claude:

• "Search our Confluence for documentation about booking workflows"
• "Get the AI Agentic Playbook page from Confluence"
• "Show me all pages in the DOCS space"
• "Find pages about rate determination in Confluence"
• "Get the child pages of page ID 123456"
• "Sync all pages from the DOCS space to local files"
• "Sync all API documentation pages matching 'API' query"
• "Push markdown file document.md to Confluence"
• "Push all markdown files from ./docs directory to Confluence"

Integration with AI Agents

This MCP server enables your AI agents (from the playbook) to:

1. Retrieve SOPs - Agents can fetch standard operating procedures

   // Rate Agent example
   const sopContent = await mcp.call('search_confluence', {
     query: 'text ~ "rate calculation SOP"'
   });
   

2. Access Knowledge Base - Build RAG pipeline with Confluence as source

   // Learning Agent example
   const bestPractices = await mcp.call('get_page_by_title', {
     title: 'Best Practices - Booking Validation',
     spaceKey: 'DOCS'
   });
   

3. Context-Aware Assistance - Provide agents with real-time documentation

   // Exception Handler example
   const dgProcedure = await mcp.call('search_confluence', {
     query: 'DG Class 3 handling procedure',
     spaceKey: 'COMPLIANCE'
   });
   

Use Cases (logistics agent examples)

1. SOP Retrieval

User: "What's the DG process for Class 3 cargo?"
  ↓
Agent searches Confluence: search_confluence("DG Class 3 procedure")
  ↓
Returns: Complete SOP with approval workflow
  ↓
Agent answers with citations

2. Master Data Validation

Booking Validator needs to check customer policies
  ↓
Searches: get_page_by_title("Customer X - Shipping Policy", "CUSTOMERS")
  ↓
Validates booking against documented policies

3. Learning Agent Improvement

Learning Agent detects pattern: "50% shipper mismatches"
  ↓
Searches Confluence: search_confluence("shipper master data rules")
  ↓
Finds updated SOP: "Always use legal name, not trade name"
  ↓
Updates agent prompt with Confluence documentation

4. Exception Handler Context

Exception: "Customs clearance delayed"
  ↓
Agent searches: search_confluence("customs clearance troubleshooting")
  ↓
Retrieves relevant procedures
  ↓
Suggests actions to operator with documentation links

Troubleshooting

Authentication Errors

• Verify your API token is correct
• Check that your email matches your Atlassian account
• Ensure the token has sufficient permissions

Page Not Found

• Verify the space key is correct
• Check page permissions (must be readable by your account)
• Try searching by ID instead of title

Connection Errors

• Verify CONFLUENCE_BASE_URL format (include https://)
• Check network/firewall settings
• Ensure your Confluence instance is accessible

Development

# Watch mode for development
npm run dev

# Build
npm run build

# Run locally
npm start

Security Notes

⚠️ Important Security Considerations:

1. API Token Storage: Never commit .env file to git
2. Least Privilege: Create API token with minimum required permissions
3. Token Rotation: Rotate tokens regularly (every 90 days)
4. Access Logging: Monitor token usage in Atlassian audit logs
5. Scope Restriction: Limit access to specific spaces if possible

Roadmap

Future enhancements:

• [x] Sync Confluence docs to local markdown files
• [x] Push markdown files to Confluence (create/update pages)
• [ ] Add comments to pages
• [ ] Attachment download
• [ ] Page versioning and history
• [ ] Advanced CQL query builder
• [ ] Caching layer for frequently accessed pages
• [ ] Webhook integration for real-time updates
• [ ] Incremental sync (only sync changed pages)
• [ ] Sync with git integration

License

MIT

Related Documentation

• Model Context Protocol Spec
• Confluence REST API Docs