Confluence MCP Server

A Model Context Protocol (MCP) server that integrates Confluence with Claude Desktop and other AI assistants, enabling natural language interactions with your Confluence documentation.

🚀 Features

Search Pages: Find documentation using natural language or CQL queries
Content Retrieval: Get full page content with formatting preserved
Space Exploration: List and navigate through your Confluence space
Page Hierarchy: Explore parent-child relationships between pages
Title-based Search: Find pages by exact title matches
Real-time Integration: Direct integration with Claude Desktop for seamless AI assistance

📋 Prerequisites

Node.js (v18.0.0 or higher)
npm (v8.0.0 or higher)
Confluence Cloud account with API access
Claude Desktop (for AI integration)

🔧 Installation

Option 1: Global Installation (Recommended)

# Clone the repository
git clone https://github.com/alirezarezvani/confluence-mcp-server.git
cd confluence-mcp-server

# Install dependencies
npm install

# Build the project
npm run build

# Install globally for easy access
npm run install-global

Option 2: Local Installation

# Clone the repository
git clone https://github.com/alirezarezvani/confluence-mcp-server.git
cd confluence-mcp-server

# Install dependencies and build
npm install
npm run build

⚙️ Configuration

1. Get Confluence API Credentials

API Token:
- Go to Atlassian Account Settings
- Click "Create API token"
- Copy the generated token (save it securely!)
Space Key:
- Navigate to your Confluence space
- Check the URL: https://your-org.atlassian.net/wiki/spaces/SPACEKEY/
- The SPACEKEY is what you need
Base URL:
- Usually https://your-org.atlassian.net (without /wiki)

2. Environment Setup

Create a .env file in the project root:

CONFLUENCE_BASE_URL=https://your-org.atlassian.net
CONFLUENCE_EMAIL=your-email@company.com
CONFLUENCE_API_TOKEN=your-api-token-here
CONFLUENCE_SPACE_KEY=YOUR_SPACE_KEY

3. Validate Configuration

# Test your environment variables
npm run validate-env

# Test the server connection
npm start

🤖 Claude Desktop Integration

Configuration File Location

macOS: ~/Library/Application Support/Claude/claude_desktop_config.json Windows: %APPDATA%\Claude\claude_desktop_config.json Linux: ~/.config/Claude/claude_desktop_config.json

Configuration Options

Option 1: Global Installation

{
  "mcpServers": {
    "confluence": {
      "command": "confluence-mcp",
      "env": {
        "CONFLUENCE_BASE_URL": "https://your-org.atlassian.net",
        "CONFLUENCE_EMAIL": "your-email@company.com",
        "CONFLUENCE_API_TOKEN": "your-api-token",
        "CONFLUENCE_SPACE_KEY": "YOUR_SPACE_KEY"
      }
    }
  }
}

Option 2: Local Installation

{
  "mcpServers": {
    "confluence": {
      "command": "node",
      "args": ["/full/path/to/confluence-mcp-server/dist/confluence-mcp-server.js"],
      "env": {
        "CONFLUENCE_BASE_URL": "https://your-org.atlassian.net",
        "CONFLUENCE_EMAIL": "your-email@company.com",
        "CONFLUENCE_API_TOKEN": "your-api-token",
        "CONFLUENCE_SPACE_KEY": "YOUR_SPACE_KEY"
      }
    }
  }
}

Activation

Save the configuration file
Restart Claude Desktop completely (Cmd+Q then reopen)
Look for MCP tools in the Claude Desktop interface

🛠️ Available Tools

1. search_confluence_pages

Search for pages using text queries or CQL.

Usage Examples:

"Search for 'API documentation' in Confluence"
"Find pages about React development"
"Look for troubleshooting guides"

2. get_page_content

Retrieve full content of a specific page.

Usage Examples:

"Get the content of page ID 12345"
"Show me what's in the 'Setup Guide' page"

3. list_space_pages

List all pages in your Confluence space.

Usage Examples:

"List all pages in our Confluence space"
"Show me the 25 most recent pages"

4. get_page_hierarchy

Explore parent-child page relationships.

Usage Examples:

"Show me all child pages under 'Documentation'"
"What are the sub-pages of the architecture section?"

5. get_page_by_title

Find pages by exact title match.

Usage Examples:

"Find the page titled 'Development Workflow'"
"Get the 'Onboarding Checklist' page"

💬 Usage Examples

Team Collaboration

"Help me find our deployment process documentation"
"What's the latest information about our API endpoints?"
"Show me all pages related to the mobile app project"
"Get me the content from our coding standards page"

Project Management

"Find all documentation related to the new feature"
"What's our current architecture documentation saying about microservices?"
"Show me the troubleshooting guides for production issues"
"List all pages updated in the last month"

Development Workflow

"Search for Docker configuration examples"
"Find our Git workflow documentation"
"What's in our testing guidelines page?"
"Show me the API integration examples"

🔧 Development

Scripts

# Development with auto-reload
npm run dev

# Build TypeScript to JavaScript
npm run build

# Run the built server
npm start

# Watch for changes and auto-restart
npm run watch

# Clean build directory
npm run clean

# Validate environment variables
npm run validate-env

# Run tests
npm test

# Run specific test file
npm test -- tests/path/to/test.ts

Project Structure

confluence-mcp-server/
├── src/
│   ├── confluence-mcp-server.ts  # Main server implementation
│   ├── cache/                    # Caching implementation
│   │   ├── CacheManager.ts       # Generic cache management
│   │   └── ConfluenceCache.ts    # Confluence-specific caching
│   └── monitoring/               # Performance monitoring
│       └── PerformanceMonitor.ts # Performance tracking and metrics
├── tests/
│   ├── confluence-mcp-server.test.ts  # Main server tests
│   ├── integration/              # Integration tests
│   │   └── mcp-tools.test.ts     # MCP tools integration tests
│   ├── cache/                    # Cache tests
│   │   └── CacheManager.test.ts  # Cache manager tests
│   ├── monitoring/               # Monitoring tests
│   │   └── PerformanceMonitor.test.ts # Performance monitor tests
│   └── utils/                    # Test utilities
│       └── test-utils.ts         # Mock implementations and helpers
├── dist/                         # Compiled JavaScript (after build)
├── package.json                  # Project dependencies and scripts
├── tsconfig.json                 # TypeScript configuration
├── jest.config.js                # Jest test configuration
├── .env                          # Environment variables (create this)
├── .env.test                     # Test environment variables
├── .gitignore                    # Git ignore rules
└── README.md                     # This file

🧪 Testing

The project includes a comprehensive test suite using Jest. Tests cover both unit and integration testing of the MCP server functionality.

Running Tests

# Run all tests
npm test

# Run specific test file
npm test -- tests/cache/CacheManager.test.ts

# Run tests with coverage report
npm test -- --coverage

Test Structure

Unit Tests: Test individual components in isolation
Integration Tests: Test the MCP tools and their interaction with the Confluence API
Mock Tests: Use mock implementations to simulate Confluence API responses

Test Environment

Tests use a separate .env.test file for environment variables. The test environment is automatically set up when running tests.

Recent Improvements

Fixed path issues in test imports
Improved CacheManager implementation with better edge case handling
Enhanced PerformanceMonitor with more accurate metrics
Added proper test data preparation for consistent test results
Updated Jest configuration for ES modules support

🚨 Troubleshooting

Common Issues

"Permission denied" error

chmod +x dist/confluence-mcp-server.js

"Missing environment variables"

npm run validate-env

"Cannot connect to Confluence"

Verify your API token has proper permissions
Check your base URL format (no trailing slash)
Ensure your email and space key are correct

"Claude Desktop not recognizing MCP server"

Check the configuration file path
Verify JSON syntax in the config file
Restart Claude Desktop completely
Check Claude Desktop logs for errors

Debug Mode

# Run with detailed logging
LOG_LEVEL=debug npm start

🔒 Security Considerations

API Token: Never commit your API token to version control
Environment Variables: Use .env files and keep them secure
Permissions: Ensure your API token has minimal required permissions
Network: Consider using VPN for sensitive corporate documentation

🤝 Contributing

We welcome contributions! Please see our Contributing Guidelines for details.

Fork the repository
Create a feature branch (git checkout -b feature/amazing-feature)
Commit your changes (git commit -m 'Add amazing feature')
Push to the branch (git push origin feature/amazing-feature)
Open a Pull Request

📄 License

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

🙏 Acknowledgments

Model Context Protocol for the MCP SDK
Atlassian for the Confluence REST API
Anthropic for Claude Desktop integration

📞 Support

Issues: GitHub Issues
Discussions: GitHub Discussions
Email: alireza@example.com

🗺️ Roadmap Q2/Q3 2025

Support for multiple Confluence spaces
Page creation and editing capabilities
Comment and attachment handling
OAuth 2.0 authentication
Caching for improved performance
Docker containerization
Confluence Server (on-premise) support
Comprehensive test suite

Made with ❤️ by Alireza Rezvani

Confluence MCP Server

A Model Context Protocol (MCP) server that integrates Confluence with Claude Desktop and other AI assistants, enabling natural language interactions with your Confluence documentation.

🚀 Features

Search Pages: Find documentation using natural language or CQL queries
Content Retrieval: Get full page content with formatting preserved
Space Exploration: List and navigate through your Confluence space
Page Hierarchy: Explore parent-child relationships between pages
Title-based Search: Find pages by exact title matches
Real-time Integration: Direct integration with Claude Desktop for seamless AI assistance

📋 Prerequisites

Node.js (v18.0.0 or higher)
npm (v8.0.0 or higher)
Confluence Cloud account with API access
Claude Desktop (for AI integration)

🔧 Installation

Option 1: Global Installation (Recommended)

# Clone the repository
git clone https://github.com/alirezarezvani/confluence-mcp-server.git
cd confluence-mcp-server

# Install dependencies
npm install

# Build the project
npm run build

# Install globally for easy access
npm run install-global

Option 2: Local Installation

# Clone the repository
git clone https://github.com/alirezarezvani/confluence-mcp-server.git
cd confluence-mcp-server

# Install dependencies and build
npm install
npm run build

⚙️ Configuration

1. Get Confluence API Credentials

API Token:
- Go to Atlassian Account Settings
- Click "Create API token"
- Copy the generated token (save it securely!)
Space Key:
- Navigate to your Confluence space
- Check the URL: https://your-org.atlassian.net/wiki/spaces/SPACEKEY/
- The SPACEKEY is what you need
Base URL:
- Usually https://your-org.atlassian.net (without /wiki)

2. Environment Setup

Create a .env file in the project root:

CONFLUENCE_BASE_URL=https://your-org.atlassian.net
CONFLUENCE_EMAIL=your-email@company.com
CONFLUENCE_API_TOKEN=your-api-token-here
CONFLUENCE_SPACE_KEY=YOUR_SPACE_KEY

3. Validate Configuration

# Test your environment variables
npm run validate-env

# Test the server connection
npm start

🤖 Claude Desktop Integration

Configuration File Location

macOS: ~/Library/Application Support/Claude/claude_desktop_config.json Windows: %APPDATA%\Claude\claude_desktop_config.json Linux: ~/.config/Claude/claude_desktop_config.json

Configuration Options

Option 1: Global Installation

{
  "mcpServers": {
    "confluence": {
      "command": "confluence-mcp",
      "env": {
        "CONFLUENCE_BASE_URL": "https://your-org.atlassian.net",
        "CONFLUENCE_EMAIL": "your-email@company.com",
        "CONFLUENCE_API_TOKEN": "your-api-token",
        "CONFLUENCE_SPACE_KEY": "YOUR_SPACE_KEY"
      }
    }
  }
}

Option 2: Local Installation

{
  "mcpServers": {
    "confluence": {
      "command": "node",
      "args": ["/full/path/to/confluence-mcp-server/dist/confluence-mcp-server.js"],
      "env": {
        "CONFLUENCE_BASE_URL": "https://your-org.atlassian.net",
        "CONFLUENCE_EMAIL": "your-email@company.com",
        "CONFLUENCE_API_TOKEN": "your-api-token",
        "CONFLUENCE_SPACE_KEY": "YOUR_SPACE_KEY"
      }
    }
  }
}

Activation

Save the configuration file
Restart Claude Desktop completely (Cmd+Q then reopen)
Look for MCP tools in the Claude Desktop interface

🛠️ Available Tools

1. search_confluence_pages

Search for pages using text queries or CQL.

Usage Examples:

"Search for 'API documentation' in Confluence"
"Find pages about React development"
"Look for troubleshooting guides"

2. get_page_content

Retrieve full content of a specific page.

Usage Examples:

"Get the content of page ID 12345"
"Show me what's in the 'Setup Guide' page"

3. list_space_pages

List all pages in your Confluence space.

Usage Examples:

"List all pages in our Confluence space"
"Show me the 25 most recent pages"

4. get_page_hierarchy

Explore parent-child page relationships.

Usage Examples:

"Show me all child pages under 'Documentation'"
"What are the sub-pages of the architecture section?"

5. get_page_by_title

Find pages by exact title match.

Usage Examples:

"Find the page titled 'Development Workflow'"
"Get the 'Onboarding Checklist' page"

💬 Usage Examples

Team Collaboration

"Help me find our deployment process documentation"
"What's the latest information about our API endpoints?"
"Show me all pages related to the mobile app project"
"Get me the content from our coding standards page"

Project Management

"Find all documentation related to the new feature"
"What's our current architecture documentation saying about microservices?"
"Show me the troubleshooting guides for production issues"
"List all pages updated in the last month"

Development Workflow

"Search for Docker configuration examples"
"Find our Git workflow documentation"
"What's in our testing guidelines page?"
"Show me the API integration examples"

🔧 Development

Scripts

# Development with auto-reload
npm run dev

# Build TypeScript to JavaScript
npm run build

# Run the built server
npm start

# Watch for changes and auto-restart
npm run watch

# Clean build directory
npm run clean

# Validate environment variables
npm run validate-env

# Run tests
npm test

# Run specific test file
npm test -- tests/path/to/test.ts

Project Structure

confluence-mcp-server/
├── src/
│   ├── confluence-mcp-server.ts  # Main server implementation
│   ├── cache/                    # Caching implementation
│   │   ├── CacheManager.ts       # Generic cache management
│   │   └── ConfluenceCache.ts    # Confluence-specific caching
│   └── monitoring/               # Performance monitoring
│       └── PerformanceMonitor.ts # Performance tracking and metrics
├── tests/
│   ├── confluence-mcp-server.test.ts  # Main server tests
│   ├── integration/              # Integration tests
│   │   └── mcp-tools.test.ts     # MCP tools integration tests
│   ├── cache/                    # Cache tests
│   │   └── CacheManager.test.ts  # Cache manager tests
│   ├── monitoring/               # Monitoring tests
│   │   └── PerformanceMonitor.test.ts # Performance monitor tests
│   └── utils/                    # Test utilities
│       └── test-utils.ts         # Mock implementations and helpers
├── dist/                         # Compiled JavaScript (after build)
├── package.json                  # Project dependencies and scripts
├── tsconfig.json                 # TypeScript configuration
├── jest.config.js                # Jest test configuration
├── .env                          # Environment variables (create this)
├── .env.test                     # Test environment variables
├── .gitignore                    # Git ignore rules
└── README.md                     # This file

🧪 Testing

The project includes a comprehensive test suite using Jest. Tests cover both unit and integration testing of the MCP server functionality.

Running Tests

# Run all tests
npm test

# Run specific test file
npm test -- tests/cache/CacheManager.test.ts

# Run tests with coverage report
npm test -- --coverage

Test Structure

Unit Tests: Test individual components in isolation
Integration Tests: Test the MCP tools and their interaction with the Confluence API
Mock Tests: Use mock implementations to simulate Confluence API responses

Test Environment

Tests use a separate .env.test file for environment variables. The test environment is automatically set up when running tests.

Recent Improvements

Fixed path issues in test imports
Improved CacheManager implementation with better edge case handling
Enhanced PerformanceMonitor with more accurate metrics
Added proper test data preparation for consistent test results
Updated Jest configuration for ES modules support

🚨 Troubleshooting

Common Issues

"Permission denied" error

chmod +x dist/confluence-mcp-server.js

"Missing environment variables"

npm run validate-env

"Cannot connect to Confluence"

Verify your API token has proper permissions
Check your base URL format (no trailing slash)
Ensure your email and space key are correct

"Claude Desktop not recognizing MCP server"

Check the configuration file path
Verify JSON syntax in the config file
Restart Claude Desktop completely
Check Claude Desktop logs for errors

Debug Mode

# Run with detailed logging
LOG_LEVEL=debug npm start

🔒 Security Considerations

API Token: Never commit your API token to version control
Environment Variables: Use .env files and keep them secure
Permissions: Ensure your API token has minimal required permissions
Network: Consider using VPN for sensitive corporate documentation

🤝 Contributing

We welcome contributions! Please see our Contributing Guidelines for details.

Fork the repository
Create a feature branch (git checkout -b feature/amazing-feature)
Commit your changes (git commit -m 'Add amazing feature')
Push to the branch (git push origin feature/amazing-feature)
Open a Pull Request

📄 License

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

🙏 Acknowledgments

Model Context Protocol for the MCP SDK
Atlassian for the Confluence REST API
Anthropic for Claude Desktop integration

📞 Support

Issues: GitHub Issues
Discussions: GitHub Discussions
Email: alireza@example.com

🗺️ Roadmap Q2/Q3 2025

Support for multiple Confluence spaces
Page creation and editing capabilities
Comment and attachment handling
OAuth 2.0 authentication
Caching for improved performance
Docker containerization
Confluence Server (on-premise) support
Comprehensive test suite

Made with ❤️ by Alireza Rezvani