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:
- 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
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"
"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
📞 Support
🗺️ Roadmap Q2/Q3 2025
Made with ❤️ by Alireza Rezvani