Content
# 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)
```bash
# 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
```bash
# 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
1. **API Token**:
- Go to [Atlassian Account Settings](https://id.atlassian.com/manage-profile/security/api-tokens)
- Click "Create API token"
- Copy the generated token (save it securely!)
2. **Space Key**:
- Navigate to your Confluence space
- Check the URL: `https://your-org.atlassian.net/wiki/spaces/SPACEKEY/`
- The `SPACEKEY` is what you need
3. **Base URL**:
- Usually `https://your-org.atlassian.net` (without `/wiki`)
### 2. Environment Setup
Create a `.env` file in the project root:
```env
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
```bash
# 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
```json
{
"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
```json
{
"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
1. Save the configuration file
2. Restart Claude Desktop completely (`Cmd+Q` then reopen)
3. 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
```bash
# 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
```text
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
```bash
# 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
```bash
chmod +x dist/confluence-mcp-server.js
```
#### "Missing environment variables"
```bash
npm run validate-env
```
#### "Cannot connect to Confluence"
1. Verify your API token has proper permissions
2. Check your base URL format (no trailing slash)
3. Ensure your email and space key are correct
#### "Claude Desktop not recognizing MCP server"
1. Check the configuration file path
2. Verify JSON syntax in the config file
3. Restart Claude Desktop completely
4. Check Claude Desktop logs for errors
### Debug Mode
```bash
# 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](CONTRIBUTING.md) for details.
1. Fork the repository
2. Create a feature branch (`git checkout -b feature/amazing-feature`)
3. Commit your changes (`git commit -m 'Add amazing feature'`)
4. Push to the branch (`git push origin feature/amazing-feature`)
5. Open a Pull Request
## 📄 License
This project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.
## 🙏 Acknowledgments
- [Model Context Protocol](https://github.com/modelcontextprotocol) for the MCP SDK
- [Atlassian](https://www.atlassian.com/) for the Confluence REST API
- [Anthropic](https://www.anthropic.com/) for Claude Desktop integration
## 📞 Support
- **Issues**: [GitHub Issues](https://github.com/alirezarezvani/confluence-mcp-server/issues)
- **Discussions**: [GitHub Discussions](https://github.com/alirezarezvani/confluence-mcp-server/discussions)
- **Email**: [alireza@example.com](mailto:info@rezarezvani.com)
## 🗺️ Roadmap Q2/Q3 2025
- [ ] Support for multiple Confluence spaces
- [ ] Page creation and editing capabilities
- [ ] Comment and attachment handling
- [ ] OAuth 2.0 authentication
- [x] Caching for improved performance
- [ ] Docker containerization
- [ ] Confluence Server (on-premise) support
- [x] Comprehensive test suite
---
**Made with ❤️ by [Alireza Rezvani](https://github.com/alirezarezvani)**
