Confluence MCP Server

<div align="center"> # 🌐 Confluence MCP Server [](https://www.typescriptlang.org/) [](https://bun.sh/) [](https://www.atlassian.com/software/confluence) [](https://opensource.org/licenses/MIT) [](https://modelcontextprotocol.io) <p align="center"> <b>A powerful Model Context Protocol (MCP) server that brings Atlassian Confluence integration directly to any editor or application that supports MCP</b> </p> </div> --- ## ✨ Features ### 🚀 New in v0.3.0 - Optimized Architecture - **9 Strategic MCP Tools** - Optimized from 8 tools with enhanced workflow capabilities - **Domain-Based Architecture** - Clean separation into 3 domains: Spaces, Pages, and Search - **Enhanced Navigation** - New tools for space lookup, page hierarchy, and content discovery - **Improved Performance** - 1871 tests passing with optimized build process ### 📚 **Access Confluence Directly From Your Editor** - Browse your Confluence spaces without leaving your IDE - Get detailed page information with formatted content - Navigate page hierarchies with child page discovery - Create, update, and manage Confluence content directly ### 🔍 **Powerful Search Capabilities** - Search pages using text queries or advanced CQL (Confluence Query Language) - Support for space filtering, content type filtering, and result ordering - Rich markdown formatting with page previews and direct links - Renamed `confluence_search_pages` to `confluence_search` for simplicity ### 📝 **Smart Content Processing** - Automatic conversion of Confluence's storage format to readable markdown - Support for formatted text, tables, macros, and attachments - Full CRUD operations for page management - Strategic workflow tools for better user experience ## 🚀 Quick Start ### Installation The easiest way to use this MCP server is to install it directly via npm/bunx. No local setup required! #### For Claude Desktop Add this configuration to your Claude Desktop MCP settings: ```json { "mcpServers": { "Confluence Tools": { "command": "bunx", "args": ["-y", "@dsazz/mcp-confluence@latest"], "env": { "CONFLUENCE_HOST_URL": "https://your-domain.atlassian.net", "CONFLUENCE_USER_EMAIL": "your-email@example.com", "CONFLUENCE_API_TOKEN": "your-confluence-api-token" } } } } ``` #### For Cursor IDE Add this configuration to your Cursor IDE MCP settings: ```json { "mcpServers": { "Confluence Tools": { "command": "bunx", "args": ["-y", "@dsazz/mcp-confluence@latest"], "env": { "CONFLUENCE_HOST_URL": "https://your-domain.atlassian.net", "CONFLUENCE_USER_EMAIL": "your-email@example.com", "CONFLUENCE_API_TOKEN": "your-confluence-api-token" } } } } ``` #### For Any MCP Client Use this configuration pattern for any MCP-compatible client: ```json { "mcpServers": { "Confluence Tools": { "command": "bunx", "args": ["-y", "@dsazz/mcp-confluence@latest"], "env": { "CONFLUENCE_HOST_URL": "https://your-domain.atlassian.net", "CONFLUENCE_USER_EMAIL": "your-email@example.com", "CONFLUENCE_API_TOKEN": "your-confluence-api-token" } } } } ``` > **🔑 Getting Your Confluence 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 Confluence") > 4. Copy the token and use it in your configuration > 5. **Important**: Use the token exactly as provided (no quotes needed in the env section) ### Alternative: Using npx instead of bunx If you prefer npx over bunx, you can also use: ```json { "mcpServers": { "Confluence Tools": { "command": "npx", "args": ["-y", "@dsazz/mcp-confluence@latest"], "env": { "CONFLUENCE_HOST_URL": "https://your-domain.atlassian.net", "CONFLUENCE_USER_EMAIL": "your-email@example.com", "CONFLUENCE_API_TOKEN": "your-confluence-api-token" } } } } ``` ### Testing Your Setup After adding the configuration: 1. Restart your MCP client (Claude Desktop, Cursor, etc.) 2. Try this command to test the connection: ``` Show me my Confluence spaces. ``` That's it! You're ready to use Confluence directly from your MCP client. --- ## 🛠️ Development Setup <details> <summary>Click here if you want to develop or customize this MCP server</summary> ### Development Installation For development or customization: ```bash # Clone the repository git clone https://github.com/Dsazz/mcp-confluence.git cd mcp-confluence # Install dependencies bun install # Build the project bun run build # Set up environment variables cp .env.example .env # Edit .env with your Confluence credentials ``` ### Configuration Create a `.env` file with the following variables: ```ini CONFLUENCE_HOST_URL=https://your-domain.atlassian.net CONFLUENCE_USER_EMAIL=your-email@example.com CONFLUENCE_API_TOKEN=your-confluence-api-token NODE_ENV=development ``` ### Development Tools #### Code Quality Tools The project uses [Biome](https://biomejs.dev/) for code formatting and linting, replacing the previous ESLint setup. Biome provides: - Fast, unified formatting and linting - TypeScript-first tooling - Zero configuration needed - Consistent code style enforcement To format and lint your code: ```bash # Format code bun format # Check code for issues bun check # Type check bun typecheck ``` #### MCP Inspector The MCP Inspector is a powerful tool for testing and debugging your MCP server. ```bash # Run the inspector (no separate build step needed) bun run inspect ``` The inspector automatically: - Loads environment variables from `.env` - Cleans up occupied ports (5175, 3002) - Builds the project when needed - Starts the MCP server with your configuration - Launches the inspector UI Visit the inspector at http://localhost:5175?proxyPort=3002 The inspector UI allows you to: - View all available MCP capabilities - Execute tools and examine responses - Analyze the JSON communication - Test with different parameters For more details, see the [MCP Inspector GitHub repository](https://github.com/modelcontextprotocol/inspector). </details> ## 🧰 Available Tools ### 🌟 Strategic Workflow Tools | Tool | Description | Parameters | Returns | | ------------------------------- | ------------------------------------------------------------------ | --------------------------------- | --------------------------------- | | `confluence_get_spaces` | List accessible Confluence spaces with optional filtering | See space parameters below | Markdown-formatted list of spaces | | `confluence_get_space_by_key` | Get specific space information by space key | `spaceKey`, optional expand flags | Markdown-formatted space details | | `confluence_get_pages_by_space` | Get all pages within a specific space | `spaceId`, optional pagination | Markdown-formatted page list | | `confluence_get_page` | Get detailed information about a specific page with content | `pageId`, optional content flags | Markdown-formatted page details | | `confluence_get_child_pages` | Get child pages of a specific page for hierarchy navigation | `pageId`, optional pagination | Markdown-formatted child pages | | `confluence_search` | Search pages using text queries or CQL (renamed from search_pages) | See search parameters below | Markdown-formatted search results | | `confluence_create_page` | Create a new page in Confluence | See page creation parameters | Markdown-formatted page details | | `confluence_update_page` | Update an existing page in Confluence | See page update parameters | Markdown-formatted page details | | `confluence_delete_page` | Delete a page from Confluence | `pageId` | Confirmation message | #### Space Parameters The `confluence_get_spaces` tool supports these parameters: **Basic Options**: - `type`: String (`"global"` or `"personal"`, optional) - Filter by space type - `limit`: Number (1-100, default: 25) - Maximum number of spaces to return - `start`: Number (default: 0) - Pagination offset for large result sets **Examples**: ``` # Basic usage - get all accessible spaces confluence_get_spaces # Get only global spaces confluence_get_spaces type:"global" limit:10 # Pagination example confluence_get_spaces start:25 limit:25 ``` #### Page Parameters The `confluence_get_page` tool supports these parameters: **Required**: - `pageId`: String - The ID of the page to retrieve **Content Options**: - `includeContent`: Boolean (default: true) - Include full page content - `includeComments`: Boolean (default: false) - Include comment count - `expand`: String (optional) - Additional fields to expand (comma-separated) **Examples**: ``` # Basic usage with content confluence_get_page 12345 # Get page without content confluence_get_page 12345 includeContent:false # Get page with comments and extra data confluence_get_page 12345 includeComments:true expand:"version,space" ``` #### Search Parameters The `confluence_search` tool supports both simple and advanced search: **Basic Search**: - `query`: String - Text search query (searches titles and content) - `spaceKey`: String (optional) - Limit search to specific space - `type`: String (`"page"` or `"blogpost"`, optional) - Content type filter **Advanced Search (CQL)**: - `query`: String - Full CQL query for advanced searches - Examples: `text~"specific phrase"`, `type=page AND space.key="DEV"` **Result Options**: - `limit`: Number (1-100, default: 25) - Maximum number of results - `start`: Number (default: 0) - Pagination offset - `orderBy`: String (`"relevance"`, `"created"`, `"modified"`, `"title"`) - Sort order **Examples**: ``` # Simple text search confluence_search query:"project documentation" # Search in specific space confluence_search query:"API guide" spaceKey:"DEV" # Advanced CQL search confluence_search query:'text~"user guide" AND type=page' # Search with custom ordering confluence_search query:"meeting notes" orderBy:"modified" limit:10 ``` #### Page Management Parameters **Page Creation** (`confluence_create_page`): - `spaceId`: String - The ID of the space where the page will be created - `title`: String - The title of the new page - `content`: String - The content of the page (supports Confluence storage format) - `parentPageId`: String (optional) - The ID of the parent page - `status`: String (`"current"` or `"draft"`, default: `"current"`) - Page status **Page Update** (`confluence_update_page`): - `pageId`: String - The ID of the page to update - `title`: String (optional) - New title for the page - `content`: String (optional) - New content for the page - `versionNumber`: Number - Current version number of the page - `versionMessage`: String (optional) - Message describing the changes **Examples**: ``` # Create a new page confluence_create_page spaceId:"123456" title:"New Documentation" content:"<p>Initial content</p>" # Update an existing page confluence_update_page pageId:"789012" title:"Updated Title" content:"<p>Updated content</p>" versionNumber:2 # Get child pages for navigation confluence_get_child_pages pageId:"123456" limit:10 ``` ## 📁 Project Structure (v0.3.0 - Optimized Architecture) ``` src/ ├── core/ # Core functionality and configurations │ ├── errors/ # Error handling utilities │ ├── logging/ # Logging infrastructure │ ├── responses/ # Response formatting │ ├── server/ # MCP server setup │ ├── tools/ # Base tool patterns │ └── utils/ # General utilities ├── features/ # Feature implementations │ └── confluence/ # Confluence integration │ ├── client/ # HTTP client infrastructure │ │ ├── config/ # Client configuration │ │ ├── errors/ # Client-specific errors │ │ ├── http/ # HTTP client implementations │ │ │ ├── utils/ # HTTP utilities │ │ │ ├── v1/ # V1 API client (search) │ │ │ └── v2/ # V2 API client (CRUD) │ │ └── responses/ # Response models │ ├── domains/ # Domain-based architecture (NEW) │ │ ├── spaces/ # Space management domain │ │ │ ├── handlers/ # Space operation handlers │ │ │ ├── models/ # Space data models │ │ │ ├── use-cases/ # Space business logic │ │ │ ├── validators/ # Space validation │ │ │ └── formatters/ # Space response formatting │ │ ├── pages/ # Page management domain │ │ │ ├── handlers/ # Page operation handlers │ │ │ ├── models/ # Page data models │ │ │ ├── use-cases/ # Page business logic │ │ │ ├── validators/ # Page validation │ │ │ └── formatters/ # Page response formatting │ │ └── search/ # Search domain │ │ ├── handlers/ # Search operation handlers │ │ ├── models/ # Search data models │ │ ├── use-cases/ # Search business logic │ │ ├── validators/ # Search validation │ │ └── formatters/ # Search response formatting │ ├── shared/ # Shared utilities across domains │ │ ├── formatters/ # Common formatters │ │ └── validators/ # Common validators │ └── tools/ # MCP tool orchestration │ ├── handlers.ts # Unified tool handlers │ ├── mcp.ts # MCP tool definitions │ └── routing.ts # Tool routing logic └── test/ # Test suite (1871 tests) ├── integration/ # Integration tests ├── unit/ # Unit tests (domain-organized) │ ├── core/ # Core functionality tests │ └── features/ # Feature tests (by domain) │ └── confluence/ │ └── domains/ # Domain-specific tests │ ├── spaces/ # Space domain tests │ ├── pages/ # Page domain tests │ └── search/ # Search domain tests └── utils/ # Test utilities ``` ### Architecture Overview The Confluence MCP Server uses a **dual-client architecture** for optimal API version management: - **V1 Client** (`http-client-v1.impl.ts`): Handles search operations and CQL queries - **V2 Client** (`http-client-v2.impl.ts`): Manages CRUD operations for spaces and pages - **Operation Router** (`operation.router.ts`): Intelligently routes requests to the appropriate API version - **Factory Pattern** (`http-client.factory.ts`): Provides clean dependency injection for clients This architecture ensures: - **Optimal Performance**: Each operation uses the most suitable API version - **Future Compatibility**: Easy to add new API versions or deprecate old ones - **Clean Separation**: Clear boundaries between different API capabilities - **Type Safety**: Full TypeScript support across all client implementations ### NPM Scripts | Command | Description | | --------------- | -------------------------------------------------- | | `bun dev` | Run the server in development mode with hot reload | | `bun build` | Build the project for production | | `bun start` | Start the production server | | `bun format` | Format code using Biome | | `bun lint` | Lint code using Biome | | `bun check` | Run Biome checks on code | | `bun typecheck` | Run TypeScript type checking | | `bun test` | Run tests | | `bun inspect` | Start the MCP Inspector for debugging | ## 🔧 Troubleshooting ### NPM Installation Issues #### Package Not Found If you get a "package not found" error: ```bash # Make sure you're using the correct scoped package name bunx @dsazz/mcp-confluence@latest # Or try with explicit npm registry npm install -g @dsazz/mcp-confluence --registry https://registry.npmjs.org ``` #### Environment Variables Not Found If the server fails to start with environment variable errors: 1. **For bunx usage**: Create a `.env` file in your working directory: ```bash # Create .env file in your current directory echo "CONFLUENCE_HOST_URL=https://your-domain.atlassian.net" > .env echo "CONFLUENCE_USER_EMAIL=your-email@example.com" >> .env echo "CONFLUENCE_API_TOKEN=your-api-token" >> .env ``` 2. **For MCP configuration**: Set environment variables in your MCP config: ```json { "mcpServers": { "Confluence Tools": { "command": "bunx", "args": ["-y", "@dsazz/mcp-confluence@latest"], "env": { "CONFLUENCE_HOST_URL": "https://your-domain.atlassian.net", "CONFLUENCE_USER_EMAIL": "your-email@example.com", "CONFLUENCE_API_TOKEN": "your-api-token" } } } } ``` ### API Connection Issues #### Invalid Credentials - Verify your Confluence API token is correct - Ensure your email matches your Atlassian account - Check that your Confluence URL is correct (include https://) #### Network/Firewall Issues - Ensure your network allows connections to your Confluence instance - Check if your organization requires VPN access - Verify firewall settings allow outbound HTTPS connections ### Development Issues #### Build Failures ```bash # Clear dependencies and reinstall rm -rf node_modules bun.lockb bun install # Clean build rm -rf dist bun run build ``` #### TypeScript Errors ```bash # Run type checking bun run typecheck # Check for linting issues bun run check ``` ## 📝 Contributing We welcome contributions! Please see our [Contributing Guide](CONTRIBUTING.md) for details on: - Development workflow - Branching strategy - Commit message format - Pull request process - Code style guidelines ## 📘 Resources - [Model Context Protocol Documentation](https://modelcontextprotocol.io) - [MCP TypeScript SDK](https://github.com/modelcontextprotocol/typescript-sdk) - [MCP Specification](https://spec.modelcontextprotocol.io/specification/) - [MCP Inspector](https://github.com/modelcontextprotocol/inspector) - [Confluence REST API](https://developer.atlassian.com/cloud/confluence/rest/v2/) ## 📄 License [MIT](LICENSE) © Stanislav Stepanenko --- <div align="center"> _{Built with ❤️ for a better developer experience} </div>