# Confluence MCP Server
A Model Context Protocol (MCP) server that bridges Confluence Wiki with Large Language Models, enabling LLMs to search, read, and explore Confluence content seamlessly.
## Features
- **MCP Protocol Compliance**: Implements the official Model Context Protocol with stdio communication
- **Three Core Tools**:
- `search_confluence`: Search for pages, blog posts, and attachments
- `read_page`: Fetch full page content with automatic HTML-to-Markdown conversion
- `list_space_content`: List all pages within a Confluence workspace
- **Smart Content Conversion**: Automatically converts Confluence HTML to clean Markdown for optimal LLM context usage
- **Robust Error Handling**: Gracefully handles authentication (401) and not found (404) errors
- **Docker Support**: Optional containerization for easy deployment
## Prerequisites
- Python 3.11 or higher
- [uv](https://github.com/astral-sh/uv) (recommended) or pip
- Confluence Cloud or Server instance
- Confluence API token (generate from your Atlassian account settings)
- Docker (optional, for containerized deployment)
## Quick Start
### 1. Clone and Setup
```bash
git clone <repository-url>
cd conflience-mcp-test
```
### 2. Configure Credentials
Create a `.env` file from the example:
```bash
cp .env.example .env
```
Edit `.env` with your Confluence credentials:
```env
CONFLUENCE_URL=https://your-domain.atlassian.net
CONFLUENCE_USERNAME=your-email@example.com
CONFLUENCE_API_TOKEN=your-api-token-here
```
### 3. Install Dependencies
#### Using uv (recommended)
```bash
# Install uv if you haven't already
curl -LsSf https://astral.sh/uv/install.sh | sh
# Sync dependencies and create virtual environment
uv sync
# Activate the virtual environment
source .venv/bin/activate
```
#### Using pip
```bash
pip install -r requirements.txt
```
### 4. Test the Server
#### Option A: Using the built-in host client
Run the host client to test the MCP server:
```bash
# If using uv, prefix commands with 'uv run' or activate the venv first
uv run python host.py search_confluence '{"query": "project documentation"}'
# Or with activated venv
python host.py search_confluence '{"query": "project documentation"}'
python host.py read_page '{"page_id": "123456"}'
python host.py list_space_content '{"space_key": "TEAM"}'
```
#### Option B: Using MCP Inspector (Recommended for Development)
The [MCP Inspector](https://github.com/modelcontextprotocol/inspector) is the official testing tool for MCP servers.
**Install MCP Inspector:**
```bash
# TypeScript or Javascript
npx @modelcontextprotocol/inspector node path/to/server/index.js args...
#Python
npx @modelcontextprotocol/inspector \
uv \
--directory path/to/server \
run \
package-name \
args...
```
**Configure the server:**
The Inspector runs directly through npx without requiring installation:
```bash
# Copy the example config
cp mcp-config.example.json mcp-config.json
# Edit mcp-config.json with your Confluence credentials
```
The config should look like:
```json
{
"mcpServers": {
"confluence": {
"command": "uv",
"args": ["run", "python", "server.py"],
"env": {
"CONFLUENCE_URL": "https://your-domain.atlassian.net",
"CONFLUENCE_USERNAME": "your-email@example.com",
"CONFLUENCE_API_TOKEN": "your-api-token"
}
}
}
}
```
**Launch the Inspector:**
```bash
mcp-inspector mcp-config.json
```
This will open a web interface at `http://localhost:5173` where you can:
- View all available tools
- Test each tool with custom inputs
- See real-time request/response data
- Debug tool execution
**Note:** You can also use environment variables from `.env` by modifying the config to load from the file.
For a comprehensive testing guide including troubleshooting and advanced usage, see [TESTING.md](TESTING.md).
## Docker Deployment
The Docker container runs the MCP server with **HTTP/SSE transport** (Server-Sent Events), making it accessible over the network.
### Build the Image
```bash
docker build -t confluence-mcp .
```
### Run the Container
```bash
# Run with environment file
docker run --rm -p 8000:8000 --env-file .env confluence-mcp
# Or pass environment variables directly
docker run --rm -p 8000:8000 \
-e CONFLUENCE_URL="https://your-domain.atlassian.net" \
-e CONFLUENCE_USERNAME="your-email@example.com" \
-e CONFLUENCE_API_TOKEN="your-token" \
confluence-mcp
```
### Connect to the Docker Container
Once the container is running, use the host client with the `--http` flag:
```bash
# Test from host machine
python host.py --http http://localhost:8000 search_confluence '{"query": "test"}'
python host.py --http http://localhost:8000 read_page '{"page_id": "123456"}'
# Test from Docker container
python host.py --http http://localhost:8000/sse list_space_content '{"space_key": "TEAM"}'
# Automatically uses "my-server" if it's the only one
npx @modelcontextprotocol/inspector --config mcp-config.json --server confluence-sse
```
**Architecture:**
- **Server Transport**: HTTP/SSE (Server-Sent Events over port 8000)
- **Client Connection**: Uses `--http` flag to connect via HTTP
- **Benefits**: Can be accessed remotely, scales horizontally, works with load balancers
## Architecture
This project implements the Model Context Protocol (MCP), which allows LLMs to interact with external tools and data sources. The server supports **two transport modes**:
### Local Mode (stdio)
```
┌─────────────────┐ ┌──────────────────┐ ┌─────────────────┐
│ LLM Client │◄───────►│ MCP Server │◄───────►│ Confluence │
│ (host.py) │ stdio │ (server.py) │ API │ Wiki │
└─────────────────┘ └──────────────────┘ └─────────────────┘
```
### Docker Mode (HTTP/SSE)
```
┌─────────────────┐ ┌──────────────────┐ ┌─────────────────┐
│ LLM Client │◄───────►│ MCP Server │◄───────►│ Confluence │
│ (host.py) │HTTP/SSE │ (Docker) │ API │ Wiki │
│ --http flag │ :8000 │ (server.py) │ │ │
└─────────────────┘ └──────────────────┘ └─────────────────┘
```
**Transport Options:**
- **stdio**: For local development and testing
- **HTTP/SSE**: For containerized deployment, remote access, and production use
## API Tools
### search_confluence
Search for content across your Confluence instance.
**Input:**
```json
{
"query": "search terms"
}
```
**Output:**
```json
{
"results": [
{
"title": "Page Title",
"type": "page",
"id": "123456"
}
]
}
```
### read_page
Fetch the full content of a Confluence page, converted to Markdown.
**Input:**
```json
{
"page_id": "123456"
}
```
**Output:**
```json
{
"title": "Page Title",
"content": "# Markdown content here...",
"page_id": "123456"
}
```
### list_space_content
List all pages within a specific Confluence space.
**Input:**
```json
{
"space_key": "TEAM"
}
```
**Output:**
```json
{
"space_key": "TEAM",
"pages": [
{
"title": "Page Title",
"id": "123456"
}
],
"total": 42
}
```
## Development
### Project Structure
- `server.py` - MCP server implementation using FastMCP
- `host.py` - MCP client for testing
- `pyproject.toml` - Project metadata and dependencies (uv configuration)
- `requirements.txt` - Python dependencies (for pip compatibility)
- `Dockerfile` - Container configuration
- `.env.example` - Environment variables template
- `mcp-config.example.json` - MCP Inspector configuration template
- `func_req.md` - Functional requirements specification
- `TESTING.md` - Comprehensive testing guide with troubleshooting
### Common uv Commands
```bash
# Install dependencies
uv sync
# Run server locally (stdio mode)
uv run python server.py
# Run server with HTTP/SSE mode
uv run python server.py --transport sse --host 0.0.0.0 --port 8000
# Run client (stdio mode)
uv run python host.py search_confluence '{"query": "test"}'
# Run client (HTTP mode)
uv run python host.py --http http://localhost:8000 search_confluence '{"query": "test"}'
# Add a new dependency
uv add package-name
# Remove a dependency
uv remove package-name
# Update all dependencies
uv sync --upgrade
# Show installed packages
uv pip list
```
### Requirements Alignment
This implementation follows the requirements specified in `func_req.md`:
- ✅ REQ-01: Confluence API integration with search, read, and list tools
- ✅ REQ-01: HTML to Markdown conversion for LLM context efficiency
- ✅ REQ-01: Error handling for 401 and 404 responses
- ✅ REQ-02: Docker containerization with stdio communication
- ✅ REQ-02: Environment-based configuration
- ✅ REQ-03: Simple MCP host client with CLI interface
## Contributing
This project follows PEP 8 coding conventions. When contributing:
1. Ensure all three tools maintain backward compatibility
2. Add appropriate error handling for new API calls
3. Update documentation for new features
4. Test with both local and Docker deployment
## License
[Your License Here]
## Resources
- [Model Context Protocol Documentation](https://modelcontextprotocol.io/)
- [Confluence Cloud REST API](https://developer.atlassian.com/cloud/confluence/rest/)
- [FastMCP Documentation](https://github.com/jlowin/fastmcp)
# confluence-mcp-container
