# 🚀 Awesome Confluence MCP Server
**The most token-efficient way for AI agents to browse and analyze Confluence documentation.**
[](https://modelcontextprotocol.io)
[](https://www.python.org)
[](LICENSE)
<a href="https://glama.ai/mcp/servers/@mazhar480/awesome-confluence-mcp">
<img width="380" height="200" src="https://glama.ai/mcp/servers/@mazhar480/awesome-confluence-mcp/badge" alt="Glama MCP Server Badge" />
</a>
**Topics:** `mcp-server` `python` `confluence-api` `ai-agents` `token-optimization` `markdown` `fastmcp`
---
## 📊 Token Savings at a Glance
**Typical Confluence Page (2,000 words):**
| Format | Tokens (Avg) | Cost (GPT-4o) | Savings |
|--------|--------------|---------------|---------|
| Raw HTML | 2,500 | $0.075 | - |
| **Your Markdown** | **600** | **$0.018** | **76%** |
> **Save 60-80% on LLM tokens** by converting Confluence pages to clean Markdown format.
A professional Model Context Protocol (MCP) server that provides token-efficient Confluence integration. Fetch, search, and convert Confluence pages to Markdown, dramatically reducing token consumption while preserving formatting and structure.
## 💡 Why Markdown Matters
**The Token-Saving Advantage:**
When working with LLMs, every token counts. Confluence pages in raw HTML format consume **3-5x more tokens** than the same content in Markdown:
- **HTML Format:** ~2,500 tokens for a typical page
- **Markdown Format:** ~500-800 tokens for the same page
- **Savings:** 60-80% reduction in token usage
This means:
- ✅ **Lower API costs** - Fewer tokens = less money spent
- ✅ **Faster responses** - Less data to process
- ✅ **Better context** - Fit more pages in your context window
- ✅ **Cleaner output** - Markdown is easier for LLMs to understand and work with
## ✨ Features
- **🔍 List Spaces** - Browse all accessible Confluence spaces
- **🔎 Search Pages** - Find pages by title or content with optional space filtering
- **📄 Fetch as Markdown** - Convert any Confluence page to clean, token-efficient Markdown
- **🔐 Secure Authentication** - Uses Atlassian API tokens (never store passwords)
- **⚡ Fast & Reliable** - Built with FastMCP for optimal performance
- **🛡️ Error Handling** - Comprehensive validation and helpful error messages
## 🚀 Quick Start
### 1. Installation
```bash
# Clone the repository
git clone https://github.com/mazhar480/awesome-confluence-mcp.git
cd awesome-confluence-mcp
# Install with pip
pip install -e .
```
### 2. Get Your Atlassian API Token
1. Go to [Atlassian API Tokens](https://id.atlassian.com/manage-profile/security/api-tokens)
2. Click **Create API token**
3. Give it a name (e.g., "MCP Server")
4. Copy the token (you won't see it again!)
### 3. Configure Environment
```bash
# Copy the example file
cp .env.example .env
# Edit .env with your credentials
CONFLUENCE_URL=https://your-domain.atlassian.net
CONFLUENCE_EMAIL=your.email@example.com
CONFLUENCE_API_TOKEN=your_api_token_here
```
### 4. Configure Your MCP Client
#### For Claude Desktop
Add to your `claude_desktop_config.json`:
```json
{
"mcpServers": {
"confluence": {
"command": "python",
"args": ["-m", "server"],
"cwd": "/path/to/awesome-confluence-mcp",
"env": {
"CONFLUENCE_URL": "https://your-domain.atlassian.net",
"CONFLUENCE_EMAIL": "your.email@example.com",
"CONFLUENCE_API_TOKEN": "your_api_token_here"
}
}
}
}
```
#### For Cline (VS Code Extension)
Add to your MCP settings:
```json
{
"confluence": {
"command": "python",
"args": ["-m", "server"],
"cwd": "/path/to/awesome-confluence-mcp"
}
}
```
Make sure your `.env` file is configured in the project directory.
## 🔧 Available Tools
### `list_spaces`
List all Confluence spaces you have access to.
**Parameters:**
- `limit` (optional): Maximum number of spaces to return (1-100, default: 25)
**Example:**
```
List my Confluence spaces
```
**Returns:**
```json
{
"total": 3,
"spaces": [
{
"key": "DOCS",
"name": "Documentation",
"type": "global",
"id": "123456",
"url": "https://your-domain.atlassian.net/wiki/spaces/DOCS"
}
]
}
```
### `search_pages`
Search for pages by title or content.
**Parameters:**
- `query` (required): Search term to match against titles and content
- `space_key` (optional): Limit search to a specific space
- `limit` (optional): Maximum results to return (1-50, default: 10)
**Example:**
```
Search for pages about "API documentation" in the DOCS space
```
**Returns:**
```json
{
"total": 5,
"query": "API documentation",
"space_key": "DOCS",
"pages": [
{
"id": "789012",
"title": "REST API Documentation",
"type": "page",
"space": {
"key": "DOCS",
"name": "Documentation"
},
"version": 12,
"url": "https://your-domain.atlassian.net/wiki/spaces/DOCS/pages/789012"
}
]
}
```
### `fetch_page_markdown`
Fetch a page and convert it to Markdown format.
**Parameters:**
- `page_id` (required): The Confluence page ID
**Example:**
```
Fetch page 789012 as markdown
```
**Returns:**
```markdown
# REST API Documentation
**Space:** Documentation (DOCS)
**Version:** 12
**URL:** https://your-domain.atlassian.net/wiki/spaces/DOCS/pages/789012
**Labels:** api, rest, documentation
---
## Overview
This page documents our REST API endpoints...
### Authentication
All requests require an API token...
```
## 🎯 Usage Examples
### Example 1: Find and Read Documentation
```
1. "List my Confluence spaces"
2. "Search for 'onboarding' pages in the HR space"
3. "Fetch page 123456 as markdown"
```
### Example 2: Research a Topic
```
"Search for pages about 'authentication' and fetch the top 3 results as markdown"
```
The MCP server will:
1. Search for relevant pages
2. Return the search results
3. Fetch each page and convert to Markdown
4. Provide clean, token-efficient content for analysis
## 🔒 Security Best Practices
- ✅ **Never commit** your `.env` file to version control
- ✅ **Use API tokens** instead of passwords
- ✅ **Rotate tokens** regularly
- ✅ **Limit token scope** to only what's needed
- ✅ **Store tokens securely** in environment variables
## 🛠️ Development
```bash
# Install with dev dependencies
pip install -e ".[dev]"
# Run tests
pytest
# Format code
black .
# Lint code
ruff check .
```
## 🧪 Testing with MCP Inspector
Want to test the tools without writing a full client? FastMCP includes a built-in MCP Inspector:
```bash
npx @modelcontextprotocol/inspector python server.py
```
This launches a web interface where you can:
- ✅ Test all three tools interactively
- ✅ See real-time request/response data
- ✅ Validate your Confluence credentials
- ✅ Experiment with different parameters
**Perfect for:** Quick testing, debugging, and demonstrating the server to others.
## 💰 Sponsorship & Support
If this MCP server saves you time and tokens, consider sponsoring its development:
- **Individual Developers:** [GitHub Sponsors](https://github.com/sponsors/mazhar480)
- **Corporate Teams:** I support **GitHub Invoiced Billing** for bulk sponsorships. [Contact me](mailto:your.email@example.com) for custom MCP development and enterprise support.
**Why sponsor?**
- Priority bug fixes and feature requests
- Custom tool development for your workflow
- Direct support and consultation
- Help maintain this free, open-source tool
## 🤝 Contributing
Contributions are welcome! Please feel free to submit a Pull Request.
## 📝 License
This project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.
## 🙏 Acknowledgments
- Built with [FastMCP](https://github.com/jlowin/fastmcp)
- Powered by [Atlassian Confluence API](https://developer.atlassian.com/cloud/confluence/rest/v2/)
- Markdown conversion by [markdownify](https://github.com/matthewwithanm/python-markdownify)
## 📞 Support
- **Issues:** [GitHub Issues](https://github.com/mazhar480/awesome-confluence-mcp/issues)
- **Discussions:** [GitHub Discussions](https://github.com/mazhar480/awesome-confluence-mcp/discussions)
---
**Made with ❤️ for the MCP community**
