Connect AI to Your Confluence Knowledge Base

1# Connect AI to Your Confluence Knowledge Base
2 
3Transform 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.
4 
5[![NPM Version](https://img.shields.io/npm/v/@aashari/mcp-server-atlassian-confluence)](https://www.npmjs.com/package/@aashari/mcp-server-atlassian-confluence)
6 
7## What You Can Do
8 
9- **Ask AI about your documentation**: "What's our API authentication process?"
10- **Search across all spaces**: "Find all pages about security best practices"
11- **Get instant answers**: "Show me the latest release notes from the Product space"
12- **Access team knowledge**: "What are our HR policies for remote work?"
13- **Review page comments**: "Show me the discussion on the architecture document"
14- **Create and update content**: "Create a new page in the DEV space"
15 
16## Perfect For
17 
18- **Developers** who need quick access to technical documentation and API guides
19- **Product Managers** searching for requirements, specs, and project updates
20- **HR Teams** accessing policy documents and employee resources quickly
21- **Support Teams** finding troubleshooting guides and knowledge base articles
22- **Anyone** who wants to interact with Confluence using natural language
23 
24## Quick Start
25 
26Get up and running in 2 minutes:
27 
28### 1. Get Your Confluence Credentials
29 
30Generate a Confluence API Token:
311. Go to [Atlassian API Tokens](https://id.atlassian.com/manage-profile/security/api-tokens)
322. Click **Create API token**
333. Give it a name like **"AI Assistant"**
344. **Copy the generated token** immediately (you won't see it again!)
35 
36### 2. Try It Instantly
37 
38```bash
39# Set your credentials
40export ATLASSIAN_SITE_NAME="your-company"  # for your-company.atlassian.net
41export ATLASSIAN_USER_EMAIL="your.email@company.com"
42export ATLASSIAN_API_TOKEN="your_api_token"
43 
44# List your Confluence spaces (TOON format by default)
45npx -y @aashari/mcp-server-atlassian-confluence get --path "/wiki/api/v2/spaces"
46 
47# Get details about a specific space with field filtering
48npx -y @aashari/mcp-server-atlassian-confluence get \
49  --path "/wiki/api/v2/spaces/123456" \
50  --jq "{id: id, key: key, name: name, type: type}"
51 
52# Get a page with JMESPath filtering
53npx -y @aashari/mcp-server-atlassian-confluence get \
54  --path "/wiki/api/v2/pages/789" \
55  --jq "{id: id, title: title, status: status}"
56 
57# Search for pages (using CQL)
58npx -y @aashari/mcp-server-atlassian-confluence get \
59  --path "/wiki/rest/api/search" \
60  --query-params '{"cql": "type=page AND space=DEV"}'
61```
62 
63## Connect to AI Assistants
64 
65### For Claude Desktop Users
66 
67Add this to your Claude configuration file (`~/.claude/claude_desktop_config.json`):
68 
69```json
70{
71  "mcpServers": {
72    "confluence": {
73      "command": "npx",
74      "args": ["-y", "@aashari/mcp-server-atlassian-confluence"],
75      "env": {
76        "ATLASSIAN_SITE_NAME": "your-company",
77        "ATLASSIAN_USER_EMAIL": "your.email@company.com",
78        "ATLASSIAN_API_TOKEN": "your_api_token"
79      }
80    }
81  }
82}
83```
84 
85Restart Claude Desktop, and you'll see the confluence server in the status bar.
86 
87### For Other AI Assistants
88 
89Most AI assistants support MCP (Cursor AI, Continue.dev, and others). Install the server globally:
90 
91```bash
92npm install -g @aashari/mcp-server-atlassian-confluence
93```
94 
95Then configure your AI assistant to use the MCP server with STDIO transport. The binary is available as `mcp-atlassian-confluence` after global installation.
96 
97### Alternative: Configuration File
98 
99Create `~/.mcp/configs.json` for system-wide configuration:
100 
101```json
102{
103  "confluence": {
104    "environments": {
105      "ATLASSIAN_SITE_NAME": "your-company",
106      "ATLASSIAN_USER_EMAIL": "your.email@company.com",
107      "ATLASSIAN_API_TOKEN": "your_api_token"
108    }
109  }
110}
111```
112 
113**Alternative config keys:** The system also accepts `"atlassian-confluence"`, `"@aashari/mcp-server-atlassian-confluence"`, or `"mcp-server-atlassian-confluence"` instead of `"confluence"`.
114 
115### Using Environment Variables
116 
117You can also configure credentials using environment variables or a `.env` file:
118 
119```bash
120# Create a .env file in your project directory
121cat > .env << EOF
122ATLASSIAN_SITE_NAME=your-company
123ATLASSIAN_USER_EMAIL=your.email@company.com
124ATLASSIAN_API_TOKEN=your_api_token
125DEBUG=false
126EOF
127```
128 
129The server will automatically load these values from:
1301. Environment variables
1312. `.env` file in the current directory
1323. `~/.mcp/configs.json` (as shown above)
133 
134## Available Tools
135 
136This MCP server provides 5 generic tools that can access any Confluence API endpoint:
137 
138| Tool | Description |
139|------|-------------|
140| `conf_get` | GET any Confluence API endpoint (read data) |
141| `conf_post` | POST to any endpoint (create resources) |
142| `conf_put` | PUT to any endpoint (replace resources) |
143| `conf_patch` | PATCH to any endpoint (partial updates) |
144| `conf_delete` | DELETE from any endpoint (remove resources) |
145 
146### Tool Parameters
147 
148All tools share these common parameters:
149 
150- **`path`** (required): The API endpoint path (e.g., `/wiki/api/v2/spaces`)
151- **`queryParams`** (optional): Query parameters as key-value pairs (e.g., `{"limit": "25", "space-id": "123"}`)
152- **`jq`** (optional): JMESPath expression to filter/transform the response (e.g., `results[*].{id: id, title: title}`)
153- **`outputFormat`** (optional): Output format - `"toon"` (default, 30-60% fewer tokens) or `"json"`
154 
155Tools that accept a request body (`conf_post`, `conf_put`, `conf_patch`):
156 
157- **`body`** (required): Request body as a JSON object
158 
159### Common API Paths
160 
161**Spaces:**
162- `/wiki/api/v2/spaces` - List all spaces
163- `/wiki/api/v2/spaces/{id}` - Get space details
164 
165**Pages:**
166- `/wiki/api/v2/pages` - List pages (use `space-id` query param to filter)
167- `/wiki/api/v2/pages/{id}` - Get page details
168- `/wiki/api/v2/pages/{id}/body` - Get page body (use `body-format` param)
169- `/wiki/api/v2/pages/{id}/children` - Get child pages
170- `/wiki/api/v2/pages/{id}/labels` - Get page labels
171 
172**Comments:**
173- `/wiki/api/v2/pages/{id}/footer-comments` - List/add footer comments
174- `/wiki/api/v2/pages/{id}/inline-comments` - List/add inline comments
175- `/wiki/api/v2/footer-comments/{comment-id}` - Get/update/delete comment
176 
177**Blog Posts:**
178- `/wiki/api/v2/blogposts` - List blog posts
179- `/wiki/api/v2/blogposts/{id}` - Get blog post
180 
181**Search:**
182- `/wiki/rest/api/search` - Search content (use `cql` query param)
183 
184### TOON Output Format
185 
186**What is TOON?** TOON (Token-Oriented Object Notation) is a format optimized for LLM token efficiency, reducing token costs by 30-60% compared to JSON. It's the default output format for all tools.
187 
188**Benefits:**
189- Tabular arrays use fewer tokens than JSON arrays
190- Minimal syntax overhead (no quotes, brackets, commas where unnecessary)
191- Still human-readable and parseable
192 
193**When to use JSON instead:**
194- When you need standard JSON for other tools
195- When debugging or manual inspection is needed
196 
197**Example comparison:**
198```json
199// JSON format (verbose)
200{"results": [{"id": "123", "title": "My Page"}, {"id": "456", "title": "Other Page"}]}
201 
202// TOON format (efficient)
203results:
204  - id: 123
205    title: My Page
206  - id: 456
207    title: Other Page
208```
209 
210To use JSON instead of TOON, set `outputFormat: "json"` in your request.
211 
212### JMESPath Filtering
213 
214All tools support optional JMESPath (`jq`) filtering to extract specific data and reduce token costs:
215 
216```bash
217# Get just space names and keys
218npx -y @aashari/mcp-server-atlassian-confluence get \
219  --path "/wiki/api/v2/spaces" \
220  --jq "results[].{id: id, key: key, name: name}"
221 
222# Get page title and status
223npx -y @aashari/mcp-server-atlassian-confluence get \
224  --path "/wiki/api/v2/pages/123456" \
225  --jq "{id: id, title: title, status: status}"
226```
227 
228**IMPORTANT:** Always use the `jq` parameter to filter responses to only the fields you need. Unfiltered responses can be very large and expensive in token costs.
229 
230**JMESPath Syntax Reference:**
231- Official docs: [jmespath.org](https://jmespath.org)
232- Common patterns:
233  - `results[*]` - All items in results array
234  - `results[0]` - First item only
235  - `results[*].id` - Just IDs from all items
236  - `results[*].{id: id, title: title}` - Create objects with selected fields
237  - `results[?status=='current']` - Filter by condition
238 
239## Real-World Examples
240 
241### Explore Your Knowledge Base
242 
243Ask your AI assistant:
244- *"List all the spaces in our Confluence"*
245- *"Show me details about the Engineering space"*
246- *"What pages are in our Product space?"*
247- *"Find the latest pages in the Marketing space"*
248 
249### Search and Find Information
250 
251Ask your AI assistant:
252- *"Search for pages about API authentication"*
253- *"Find all documentation with 'security' in the title"*
254- *"Show me pages labeled with 'getting-started'"*
255- *"Search for content in the DEV space about deployment"*
256 
257### Access Specific Content
258 
259Ask your AI assistant:
260- *"Get the content of the API Authentication Guide page"*
261- *"Show me the onboarding checklist document"*
262- *"What's in our security policies page?"*
263- *"Display the latest release notes"*
264 
265### Create and Update Content
266 
267Ask your AI assistant:
268- *"Create a new page in the DEV space titled 'API Guide'"*
269- *"Add a comment to the architecture document"*
270- *"Update the page content with the new release info"*
271 
272## CLI Commands
273 
274The CLI mirrors the MCP tools for direct terminal access. All commands support the same parameters as the tools.
275 
276### Available Commands
277 
278- `get` - GET any Confluence endpoint
279- `post` - POST to any endpoint
280- `put` - PUT to any endpoint
281- `patch` - PATCH any endpoint
282- `delete` - DELETE from any endpoint
283 
284### CLI Parameters
285 
286**All commands:**
287- `-p, --path <path>` (required) - API endpoint path
288- `-q, --query-params <json>` (optional) - Query parameters as JSON
289- `--jq <expression>` (optional) - JMESPath filter expression
290- `-o, --output-format <format>` (optional) - Output format: `toon` (default) or `json`
291 
292**Commands with body (post, put, patch):**
293- `-b, --body <json>` (required) - Request body as JSON
294 
295### Examples
296 
297```bash
298# GET request
299npx -y @aashari/mcp-server-atlassian-confluence get --path "/wiki/api/v2/spaces"
300 
301# GET with query parameters and JMESPath filter
302npx -y @aashari/mcp-server-atlassian-confluence get \
303  --path "/wiki/api/v2/pages" \
304  --query-params '{"space-id": "123456", "limit": "10"}' \
305  --jq "results[*].{id: id, title: title}"
306 
307# GET with JSON output format
308npx -y @aashari/mcp-server-atlassian-confluence get \
309  --path "/wiki/api/v2/spaces" \
310  --output-format json
311 
312# POST request (create a page)
313npx -y @aashari/mcp-server-atlassian-confluence post \
314  --path "/wiki/api/v2/pages" \
315  --body '{"spaceId": "123456", "status": "current", "title": "New Page", "body": {"representation": "storage", "value": "<p>Content here</p>"}}'
316 
317# POST request (add a comment)
318npx -y @aashari/mcp-server-atlassian-confluence post \
319  --path "/wiki/api/v2/pages/789/footer-comments" \
320  --body '{"body": {"representation": "storage", "value": "<p>My comment</p>"}}'
321 
322# PUT request (update page - requires version increment)
323npx -y @aashari/mcp-server-atlassian-confluence put \
324  --path "/wiki/api/v2/pages/789" \
325  --body '{"id": "789", "status": "current", "title": "Updated Title", "spaceId": "123456", "body": {"representation": "storage", "value": "<p>Updated content</p>"}, "version": {"number": 2}}'
326 
327# PATCH request (partial update)
328npx -y @aashari/mcp-server-atlassian-confluence patch \
329  --path "/wiki/api/v2/spaces/123456" \
330  --body '{"name": "New Space Name"}'
331 
332# DELETE request
333npx -y @aashari/mcp-server-atlassian-confluence delete \
334  --path "/wiki/api/v2/pages/789"
335```
336 
337## Response Handling
338 
339### Large Response Truncation
340 
341When API responses exceed approximately 40,000 characters (~10,000 tokens), the server automatically truncates the response to stay within token limits. When this happens:
342 
3431. **You'll see a truncation notice** at the end of the response showing:
344   - How much of the original response is shown
345   - The original response size
346   - Guidance on accessing the full data
347 
3482. **The full raw response is saved** to a temporary file in `/tmp/mcp/` (path provided in the truncation notice)
349 
3503. **Best practices to avoid truncation:**
351   - **Always use the `jq` parameter** to filter responses to only needed fields
352   - Use `limit` query parameter to restrict result counts (e.g., `{"limit": "5"}`)
353   - Request specific resources by ID rather than listing all
354   - Use targeted CQL queries for searches
355 
356**Example of efficient filtering:**
357```bash
358# Instead of getting all space data (can be huge):
359npx -y @aashari/mcp-server-atlassian-confluence get \
360  --path "/wiki/api/v2/spaces"
361 
362# Get only the fields you need:
363npx -y @aashari/mcp-server-atlassian-confluence get \
364  --path "/wiki/api/v2/spaces" \
365  --query-params '{"limit": "10"}' \
366  --jq "results[*].{id: id, key: key, name: name}"
367```
368 
369### Debug Logging
370 
371Enable debug logging to see detailed request/response information:
372 
373```bash
374# Set DEBUG environment variable
375export DEBUG=true
376 
377# For MCP mode
378DEBUG=true npx -y @aashari/mcp-server-atlassian-confluence
379 
380# For CLI mode
381DEBUG=true npx -y @aashari/mcp-server-atlassian-confluence get --path "/wiki/api/v2/spaces"
382```
383 
384Debug logs are written to: `~/.mcp/data/@aashari-mcp-server-atlassian-confluence.[session-id].log`
385 
386## Testing & Development
387 
388### Using MCP Inspector
389 
390The MCP Inspector provides a visual interface for testing tools:
391 
392```bash
393# Install the server globally
394npm install -g @aashari/mcp-server-atlassian-confluence
395 
396# Run with MCP Inspector
397npx @modelcontextprotocol/inspector node $(which mcp-atlassian-confluence)
398```
399 
400Or use the built-in development command if you've cloned the repository:
401 
402```bash
403npm run mcp:inspect
404```
405 
406This starts the server in HTTP mode and opens the inspector UI in your browser.
407 
408### HTTP Mode for Testing
409 
410You can run the server in HTTP mode to test with curl or other HTTP clients:
411 
412```bash
413# Start server in HTTP mode
414TRANSPORT_MODE=http npx -y @aashari/mcp-server-atlassian-confluence
415```
416 
417The server will listen on `http://localhost:3000/mcp` by default. You can change the port:
418 
419```bash
420PORT=8080 TRANSPORT_MODE=http npx -y @aashari/mcp-server-atlassian-confluence
421```
422 
423**Testing with curl:**
424 
425```bash
426# Initialize session
427curl -X POST http://localhost:3000/mcp \
428  -H "Content-Type: application/json" \
429  -H "Accept: application/json, text/event-stream" \
430  -d '{"jsonrpc": "2.0", "id": 1, "method": "initialize", "params": {"protocolVersion": "2024-11-05", "clientInfo": {"name": "curl-test", "version": "1.0.0"}, "capabilities": {}}}'
431 
432# List available tools
433curl -X POST http://localhost:3000/mcp \
434  -H "Content-Type: application/json" \
435  -H "Accept: application/json, text/event-stream" \
436  -d '{"jsonrpc": "2.0", "id": 2, "method": "tools/list"}'
437 
438# Call a tool
439curl -X POST http://localhost:3000/mcp \
440  -H "Content-Type: application/json" \
441  -H "Accept: application/json, text/event-stream" \
442  -d '{"jsonrpc": "2.0", "id": 3, "method": "tools/call", "params": {"name": "conf_get", "arguments": {"path": "/wiki/api/v2/spaces", "queryParams": {"limit": "5"}}}}'
443```
444 
445The response comes as Server-Sent Events (SSE) with format:
446```
447event: message
448data: {"jsonrpc": "2.0", "id": 1, "result": {...}}
449```
450 
451## Troubleshooting
452 
453### "Authentication failed" or "403 Forbidden"
454 
4551. **Check your API Token permissions**:
456   - Go to [Atlassian API Tokens](https://id.atlassian.com/manage-profile/security/api-tokens)
457   - Make sure your token is still active and hasn't expired
458 
4592. **Verify your site name format**:
460   - If your Confluence URL is `https://mycompany.atlassian.net`
461   - Your site name should be just `mycompany`
462 
4633. **Test your credentials**:
464   ```bash
465   npx -y @aashari/mcp-server-atlassian-confluence get --path "/wiki/api/v2/spaces?limit=1"
466   ```
467 
468### "Resource not found" or "404"
469 
4701. **Check the API path**:
471   - Paths are case-sensitive
472   - Use numeric IDs for spaces and pages (not keys)
473   - Verify the resource exists in your browser
474 
4752. **Verify access permissions**:
476   - Make sure you have access to the space/page in your browser
477   - Some content may be restricted to certain users
478 
479### "No results found" when searching
480 
4811. **Try different search terms**:
482   - Use CQL syntax for advanced searches
483   - Try broader search criteria
484 
4852. **Check CQL syntax**:
486   - Validate your CQL in Confluence's advanced search first
487 
488### Claude Desktop Integration Issues
489 
4901. **Restart Claude Desktop** after updating the config file
4912. **Verify config file location**:
492   - macOS: `~/.claude/claude_desktop_config.json`
493   - Windows: `%APPDATA%\Claude\claude_desktop_config.json`
494 
495### Getting Help
496 
497If you're still having issues:
4981. Run a simple test command to verify everything works
4992. Check the [GitHub Issues](https://github.com/aashari/mcp-server-atlassian-confluence/issues) for similar problems
5003. Create a new issue with your error message and setup details
501 
502## Frequently Asked Questions
503 
504### What permissions do I need?
505 
506Your Atlassian account needs:
507- **Access to Confluence** with the appropriate permissions for the spaces you want to query
508- **API token** with appropriate permissions (automatically granted when you create one)
509 
510### Can I use this with Confluence Server (on-premise)?
511 
512Currently, this tool only supports **Confluence Cloud**. Confluence Server/Data Center support may be added in future versions.
513 
514### How do I find my site name?
515 
516Your site name is the first part of your Confluence URL:
517- URL: `https://mycompany.atlassian.net` -> Site name: `mycompany`
518- URL: `https://acme-corp.atlassian.net` -> Site name: `acme-corp`
519 
520### What AI assistants does this work with?
521 
522Any AI assistant that supports the Model Context Protocol (MCP):
523- Claude Desktop
524- Cursor AI
525- Continue.dev
526- Many others
527 
528### Is my data secure?
529 
530Yes! This tool:
531- Runs entirely on your local machine
532- Uses your own Confluence credentials
533- Never sends your data to third parties
534- Only accesses what you give it permission to access
535 
536### Can I search across all my spaces at once?
537 
538Yes! Use CQL queries for cross-space searches. For example:
539```bash
540npx -y @aashari/mcp-server-atlassian-confluence get \
541  --path "/wiki/rest/api/search" \
542  --query-params '{"cql": "type=page AND text~\"API documentation\""}'
543```
544 
545## Migration from v2.x
546 
547Version 3.0 replaces 8+ specific tools with 5 generic HTTP method tools. If you're upgrading from v2.x:
548 
549**Before (v2.x):**
550```
551conf_ls_spaces, conf_get_space, conf_ls_pages, conf_get_page,
552conf_search, conf_ls_comments, conf_add_comment, ...
553```
554 
555**After (v3.0):**
556```
557conf_get, conf_post, conf_put, conf_patch, conf_delete
558```
559 
560**Migration examples:**
561- `conf_ls_spaces` -> `conf_get` with path `/wiki/api/v2/spaces`
562- `conf_get_space` -> `conf_get` with path `/wiki/api/v2/spaces/{id}`
563- `conf_ls_pages` -> `conf_get` with path `/wiki/api/v2/pages?space-id={id}`
564- `conf_get_page` -> `conf_get` with path `/wiki/api/v2/pages/{id}`
565- `conf_search` -> `conf_get` with path `/wiki/rest/api/search?cql=...`
566- `conf_add_comment` -> `conf_post` with path `/wiki/api/v2/pages/{id}/footer-comments`
567 
568## Technical Details
569 
570### Requirements
571 
572- **Node.js**: 18.0.0 or higher
573- **MCP SDK**: 1.23.0 (uses modern `registerTool` API)
574- **Confluence**: Cloud only (Server/Data Center not supported)
575 
576### Architecture
577 
578This server follows a 5-layer architecture:
579 
5801. **Tools Layer** (`src/tools/`) - MCP tool definitions with Zod validation
5812. **CLI Layer** (`src/cli/`) - Commander-based CLI for direct testing
5823. **Controllers Layer** (`src/controllers/`) - Business logic, JMESPath filtering, output formatting
5834. **Services Layer** (`src/services/`) - Confluence API communication
5845. **Utils Layer** (`src/utils/`) - Shared utilities (logger, config, formatters, TOON encoder)
585 
586### Features
587 
588- **Generic HTTP method tools** - Access any Confluence API endpoint
589- **TOON output format** - 30-60% token reduction vs JSON
590- **JMESPath filtering** - Extract only needed data
591- **Response truncation** - Automatic handling of large responses
592- **Raw response logging** - Full responses saved to `/tmp/mcp/`
593- **Dual transport** - STDIO (for Claude Desktop) and HTTP (for web integrations)
594- **Debug logging** - Comprehensive logging for troubleshooting
595 
596### Version History
597 
598**v3.2.1** (Current)
599- Add raw response logging with truncation for large API responses
600- Improve dependency compatibility
601 
602**v3.2.0**
603- Modernize MCP SDK to v1.23.0 with registerTool API
604 
605**v3.1.0**
606- Add TOON output format for token-efficient LLM responses
607 
608**v3.0.0** (Breaking change)
609- Replace 8+ domain-specific tools with 5 generic HTTP method tools
610- Add JMESPath filtering support
611- Full Confluence API access via generic methods
612 
613See [CHANGELOG.md](CHANGELOG.md) for complete version history.
614 
615## Support
616 
617Need help? Here's how to get assistance:
618 
6191. **Check the troubleshooting section above** - most common issues are covered there
6202. **Visit our GitHub repository** for documentation and examples: [github.com/aashari/mcp-server-atlassian-confluence](https://github.com/aashari/mcp-server-atlassian-confluence)
6213. **Report issues** at [GitHub Issues](https://github.com/aashari/mcp-server-atlassian-confluence/issues)
6224. **Start a discussion** for feature requests or general questions
623 
624---
625 
626*Made with care for teams who want to bring AI into their knowledge management workflow.*
627