Connect AI to Your Confluence Knowledge Base

Transform how you access and interact with your team's knowledge by connecting Claude, Cursor AI, and other AI assistants directly to your Confluence spaces, pages, and documentation. Get instant answers from your knowledge base, search across all your spaces, and streamline your documentation workflow.

What You Can Do

Ask AI about your documentation: "What's our API authentication process?"
Search across all spaces: "Find all pages about security best practices"
Get instant answers: "Show me the latest release notes from the Product space"
Access team knowledge: "What are our HR policies for remote work?"
Review page comments: "Show me the discussion on the architecture document"
Create and update content: "Create a new page in the DEV space"

Perfect For

Developers who need quick access to technical documentation and API guides
Product Managers searching for requirements, specs, and project updates
HR Teams accessing policy documents and employee resources quickly
Support Teams finding troubleshooting guides and knowledge base articles
Anyone who wants to interact with Confluence using natural language

Quick Start

Get up and running in 2 minutes:

1. Get Your Confluence Credentials

Generate a Confluence API Token:

1. Go to Atlassian API Tokens

2. Click Create API token

3. Give it a name like "AI Assistant"

4. Copy the generated token immediately (you won't see it again!)

2. Try It Instantly

bash

# Set your credentials
export ATLASSIAN_SITE_NAME="your-company"  # for your-company.atlassian.net
export ATLASSIAN_USER_EMAIL="your.email@company.com"
export ATLASSIAN_API_TOKEN="your_api_token"

# List your Confluence spaces (TOON format by default)
npx -y @aashari/mcp-server-atlassian-confluence get --path "/wiki/api/v2/spaces"

# Get details about a specific space with field filtering
npx -y @aashari/mcp-server-atlassian-confluence get \
  --path "/wiki/api/v2/spaces/123456" \
  --jq "{id: id, key: key, name: name, type: type}"

# Get a page with JMESPath filtering
npx -y @aashari/mcp-server-atlassian-confluence get \
  --path "/wiki/api/v2/pages/789" \
  --jq "{id: id, title: title, status: status}"

# Search for pages (using CQL)
npx -y @aashari/mcp-server-atlassian-confluence get \
  --path "/wiki/rest/api/search" \
  --query-params '{"cql": "type=page AND space=DEV"}'

Connect to AI Assistants

For Claude Desktop Users

Add this to your Claude configuration file (~/.claude/claude_desktop_config.json):

json

{
  "mcpServers": {
    "confluence": {
      "command": "npx",
      "args": ["-y", "@aashari/mcp-server-atlassian-confluence"],
      "env": {
        "ATLASSIAN_SITE_NAME": "your-company",
        "ATLASSIAN_USER_EMAIL": "your.email@company.com",
        "ATLASSIAN_API_TOKEN": "your_api_token"
      }
    }
  }
}

Restart Claude Desktop, and you'll see the confluence server in the status bar.

For Other AI Assistants

Most AI assistants support MCP (Cursor AI, Continue.dev, and others). Install the server globally:

bash

npm install -g @aashari/mcp-server-atlassian-confluence

Then configure your AI assistant to use the MCP server with STDIO transport. The binary is available as mcp-atlassian-confluence after global installation.

Alternative: Configuration File

Create ~/.mcp/configs.json for system-wide configuration:

json

{
  "confluence": {
    "environments": {
      "ATLASSIAN_SITE_NAME": "your-company",
      "ATLASSIAN_USER_EMAIL": "your.email@company.com",
      "ATLASSIAN_API_TOKEN": "your_api_token"
    }
  }
}

Alternative config keys: The system also accepts "atlassian-confluence", "@aashari/mcp-server-atlassian-confluence", or "mcp-server-atlassian-confluence" instead of "confluence".

Using Environment Variables

You can also configure credentials using environment variables or a .env file:

bash

# Create a .env file in your project directory
cat > .env ` (required) - API endpoint path
- `-q, --query-params ` (optional) - Query parameters as JSON
- `--jq ` (optional) - JMESPath filter expression
- `-o, --output-format ` (optional) - Output format: `toon` (default) or `json`

**Commands with body (post, put, patch):**
- `-b, --body ` (required) - Request body as JSON

### Examples

GET request

npx -y @aashari/mcp-server-atlassian-confluence get --path "/wiki/api/v2/spaces"

GET with query parameters and JMESPath filter

npx -y @aashari/mcp-server-atlassian-confluence get \

--path "/wiki/api/v2/pages" \

--query-params '{"space-id": "123456", "limit": "10"}' \

--jq "results[*].{id: id, title: title}"

GET with JSON output format

npx -y @aashari/mcp-server-atlassian-confluence get \

--path "/wiki/api/v2/spaces" \

--output-format json

POST request (create a page)

npx -y @aashari/mcp-server-atlassian-confluence post \

--path "/wiki/api/v2/pages" \

--body '{"spaceId": "123456", "status": "current", "title": "New Page", "body": {"representation": "storage", "value": "Content here"}}'

POST request (add a comment)

npx -y @aashari/mcp-server-atlassian-confluence post \

--path "/wiki/api/v2/pages/789/footer-comments" \

--body '{"body": {"representation": "storage", "value": "My comment"}}'

PUT request (update page - requires version increment)

npx -y @aashari/mcp-server-atlassian-confluence put \

--path "/wiki/api/v2/pages/789" \

--body '{"id": "789", "status": "current", "title": "Updated Title", "spaceId": "123456", "body": {"representation": "storage", "value": "Updated content"}, "version": {"number": 2}}'

PATCH request (partial update)

npx -y @aashari/mcp-server-atlassian-confluence patch \

--path "/wiki/api/v2/spaces/123456" \

--body '{"name": "New Space Name"}'

DELETE request

npx -y @aashari/mcp-server-atlassian-confluence delete \

--path "/wiki/api/v2/pages/789"

code

## Response Handling

### Large Response Truncation

When API responses exceed approximately 40,000 characters (~10,000 tokens), the server automatically truncates the response to stay within token limits. When this happens:

1. **You'll see a truncation notice** at the end of the response showing:
   - How much of the original response is shown
   - The original response size
   - Guidance on accessing the full data

2. **The full raw response is saved** to a temporary file in `/tmp/mcp/` (path provided in the truncation notice)

3. **Best practices to avoid truncation:**
   - **Always use the `jq` parameter** to filter responses to only needed fields
   - Use `limit` query parameter to restrict result counts (e.g., `{"limit": "5"}`)
   - Request specific resources by ID rather than listing all
   - Use targeted CQL queries for searches

**Example of efficient filtering:**

Instead of getting all space data (can be huge):

npx -y @aashari/mcp-server-atlassian-confluence get \

--path "/wiki/api/v2/spaces"

Get only the fields you need:

npx -y @aashari/mcp-server-atlassian-confluence get \

--path "/wiki/api/v2/spaces" \

--query-params '{"limit": "10"}' \

--jq "results[*].{id: id, key: key, name: name}"

code

### Debug Logging

Enable debug logging to see detailed request/response information:

Set DEBUG environment variable

export DEBUG=true

For MCP mode

DEBUG=true npx -y @aashari/mcp-server-atlassian-confluence

For CLI mode

DEBUG=true npx -y @aashari/mcp-server-atlassian-confluence get --path "/wiki/api/v2/spaces"

code

Debug logs are written to: `~/.mcp/data/@aashari-mcp-server-atlassian-confluence.[session-id].log`

## Testing & Development

### Using MCP Inspector

The MCP Inspector provides a visual interface for testing tools:

Install the server globally

npm install -g @aashari/mcp-server-atlassian-confluence

Run with MCP Inspector

npx @modelcontextprotocol/inspector node $(which mcp-atlassian-confluence)

code

Or use the built-in development command if you've cloned the repository:

npm run mcp:inspect

code

This starts the server in HTTP mode and opens the inspector UI in your browser.

### HTTP Mode for Testing

You can run the server in HTTP mode to test with curl or other HTTP clients:

Start server in HTTP mode

TRANSPORT_MODE=http npx -y @aashari/mcp-server-atlassian-confluence

code

The server will listen on `http://localhost:3000/mcp` by default. You can change the port:

PORT=8080 TRANSPORT_MODE=http npx -y @aashari/mcp-server-atlassian-confluence

code

**Testing with curl:**

Initialize session

curl -X POST http://localhost:3000/mcp \

-H "Content-Type: application/json" \

-H "Accept: application/json, text/event-stream" \

-d '{"jsonrpc": "2.0", "id": 1, "method": "initialize", "params": {"protocolVersion": "2024-11-05", "clientInfo": {"name": "curl-test", "version": "1.0.0"}, "capabilities": {}}}'

List available tools

curl -X POST http://localhost:3000/mcp \

-H "Content-Type: application/json" \

-H "Accept: application/json, text/event-stream" \

-d '{"jsonrpc": "2.0", "id": 2, "method": "tools/list"}'

Call a tool

curl -X POST http://localhost:3000/mcp \

-H "Content-Type: application/json" \

-H "Accept: application/json, text/event-stream" \

-d '{"jsonrpc": "2.0", "id": 3, "method": "tools/call", "params": {"name": "conf_get", "arguments": {"path": "/wiki/api/v2/spaces", "queryParams": {"limit": "5"}}}}'

code

The response comes as Server-Sent Events (SSE) with format:

event: message

data: {"jsonrpc": "2.0", "id": 1, "result": {...}}

code

## Troubleshooting

### "Authentication failed" or "403 Forbidden"

1. **Check your API Token permissions**:
   - Go to [Atlassian API Tokens](https://id.atlassian.com/manage-profile/security/api-tokens)
   - Make sure your token is still active and hasn't expired

2. **Verify your site name format**:
   - If your Confluence URL is `https://mycompany.atlassian.net`
   - Your site name should be just `mycompany`

3. **Test your credentials**:

npx -y @aashari/mcp-server-atlassian-confluence get --path "/wiki/api/v2/spaces?limit=1"

code

### "Resource not found" or "404"

1. **Check the API path**:
   - Paths are case-sensitive
   - Use numeric IDs for spaces and pages (not keys)
   - Verify the resource exists in your browser

2. **Verify access permissions**:
   - Make sure you have access to the space/page in your browser
   - Some content may be restricted to certain users

### "No results found" when searching

1. **Try different search terms**:
   - Use CQL syntax for advanced searches
   - Try broader search criteria

2. **Check CQL syntax**:
   - Validate your CQL in Confluence's advanced search first

### Claude Desktop Integration Issues

1. **Restart Claude Desktop** after updating the config file
2. **Verify config file location**:
   - macOS: `~/.claude/claude_desktop_config.json`
   - Windows: `%APPDATA%\Claude\claude_desktop_config.json`

### Getting Help

If you're still having issues:
1. Run a simple test command to verify everything works
2. Check the [GitHub Issues](https://github.com/aashari/mcp-server-atlassian-confluence/issues) for similar problems
3. Create a new issue with your error message and setup details

## Frequently Asked Questions

### What permissions do I need?

Your Atlassian account needs:
- **Access to Confluence** with the appropriate permissions for the spaces you want to query
- **API token** with appropriate permissions (automatically granted when you create one)

### Can I use this with Confluence Server (on-premise)?

Currently, this tool only supports **Confluence Cloud**. Confluence Server/Data Center support may be added in future versions.

### How do I find my site name?

Your site name is the first part of your Confluence URL:
- URL: `https://mycompany.atlassian.net` -> Site name: `mycompany`
- URL: `https://acme-corp.atlassian.net` -> Site name: `acme-corp`

### What AI assistants does this work with?

Any AI assistant that supports the Model Context Protocol (MCP):
- Claude Desktop
- Cursor AI
- Continue.dev
- Many others

### Is my data secure?

Yes! This tool:
- Runs entirely on your local machine
- Uses your own Confluence credentials
- Never sends your data to third parties
- Only accesses what you give it permission to access

### Can I search across all my spaces at once?

Yes! Use CQL queries for cross-space searches. For example:

npx -y @aashari/mcp-server-atlassian-confluence get \

--path "/wiki/rest/api/search" \

--query-params '{"cql": "type=page AND text~\"API documentation\""}'

code

## Migration from v2.x

Version 3.0 replaces 8+ specific tools with 5 generic HTTP method tools. If you're upgrading from v2.x:

**Before (v2.x):**

conf_ls_spaces, conf_get_space, conf_ls_pages, conf_get_page,

conf_search, conf_ls_comments, conf_add_comment, ...

code

**After (v3.0):**

conf_get, conf_post, conf_put, conf_patch, conf_delete

code

**Migration examples:**
- `conf_ls_spaces` -> `conf_get` with path `/wiki/api/v2/spaces`
- `conf_get_space` -> `conf_get` with path `/wiki/api/v2/spaces/{id}`
- `conf_ls_pages` -> `conf_get` with path `/wiki/api/v2/pages?space-id={id}`
- `conf_get_page` -> `conf_get` with path `/wiki/api/v2/pages/{id}`
- `conf_search` -> `conf_get` with path `/wiki/rest/api/search?cql=...`
- `conf_add_comment` -> `conf_post` with path `/wiki/api/v2/pages/{id}/footer-comments`

## Technical Details

### Requirements

- **Node.js**: 18.0.0 or higher
- **MCP SDK**: 1.23.0 (uses modern `registerTool` API)
- **Confluence**: Cloud only (Server/Data Center not supported)

### Architecture

This server follows a 5-layer architecture:

1. **Tools Layer** (`src/tools/`) - MCP tool definitions with Zod validation
2. **CLI Layer** (`src/cli/`) - Commander-based CLI for direct testing
3. **Controllers Layer** (`src/controllers/`) - Business logic, JMESPath filtering, output formatting
4. **Services Layer** (`src/services/`) - Confluence API communication
5. **Utils Layer** (`src/utils/`) - Shared utilities (logger, config, formatters, TOON encoder)

### Features

- **Generic HTTP method tools** - Access any Confluence API endpoint
- **TOON output format** - 30-60% token reduction vs JSON
- **JMESPath filtering** - Extract only needed data
- **Response truncation** - Automatic handling of large responses
- **Raw response logging** - Full responses saved to `/tmp/mcp/`
- **Dual transport** - STDIO (for Claude Desktop) and HTTP (for web integrations)
- **Debug logging** - Comprehensive logging for troubleshooting

### Version History

**v3.2.1** (Current)
- Add raw response logging with truncation for large API responses
- Improve dependency compatibility

**v3.2.0**
- Modernize MCP SDK to v1.23.0 with registerTool API

**v3.1.0**
- Add TOON output format for token-efficient LLM responses

**v3.0.0** (Breaking change)
- Replace 8+ domain-specific tools with 5 generic HTTP method tools
- Add JMESPath filtering support
- Full Confluence API access via generic methods

See [CHANGELOG.md](CHANGELOG.md) for complete version history.

## Support

Need help? Here's how to get assistance:

1. **Check the troubleshooting section above** - most common issues are covered there
2. **Visit our GitHub repository** for documentation and examples: [github.com/aashari/mcp-server-atlassian-confluence](https://github.com/aashari/mcp-server-atlassian-confluence)
3. **Report issues** at [GitHub Issues](https://github.com/aashari/mcp-server-atlassian-confluence/issues)
4. **Start a discussion** for feature requests or general questions

---

*Made with care for teams who want to bring AI into their knowledge management workflow.*

Mcp Server Atlassian Confluence

Documentation

Connect AI to Your Confluence Knowledge Base

What You Can Do

Perfect For

Quick Start

1. Get Your Confluence Credentials

2. Try It Instantly

Connect to AI Assistants

For Claude Desktop Users

For Other AI Assistants

Alternative: Configuration File

Using Environment Variables

GET request

GET with query parameters and JMESPath filter

GET with JSON output format

POST request (create a page)

POST request (add a comment)

PUT request (update page - requires version increment)

PATCH request (partial update)

DELETE request

Instead of getting all space data (can be huge):

Get only the fields you need:

Set DEBUG environment variable

For MCP mode

For CLI mode

Install the server globally

Run with MCP Inspector

Start server in HTTP mode

Initialize session

List available tools

Call a tool

Similar MCP

Anilist Mcp

Mcp Ipfs

Mcp Open Library

Biomcp

Trending MCP

Playwright Mcp

Serena

Mcp Playwright

Mcp Server Cloudflare

Anilist Mcp

Mcp Ipfs

Mcp Open Library

Biomcp

Playwright Mcp

Serena

Mcp Playwright

Mcp Server Cloudflare