MCP Confluence

A Model Context Protocol (MCP) server for integrating Confluence with OpenCode. Seamlessly search, read, create, and update Confluence pages directly from your AI coding agent.

Features

• ✅ Search Confluence content by keywords
• ✅ List available spaces
• ✅ Get space content
• ✅ Read Confluence pages by ID
• ✅ Create new pages
• ✅ Update existing pages
• ✅ Full TypeScript support

Requirements

• Node.js 18+
• Confluence API credentials (email + API token)

Installation

Using npm

npm install @jsalamanc_01/mcp-confluence

Or use directly with OpenCode

npx @jsalamanc_01/mcp-confluence

Configuration

1. Get Your Confluence API Token

1. Go to https://id.atlassian.com/manage/api-tokens
2. Create a new API token
3. Copy the token and save it securely

2. Setup with OpenCode

Add this to your ~/.config/opencode/opencode.jsonc:

{
  "mcp": {
    "confluence": {
      "type": "local",
      "command": ["npx", "-y", "@jsalamanc_01/mcp-confluence"],
      "enabled": true,
      "environment": {
        "CONFLUENCE_BASE_URL": "https://your-instance.atlassian.net",
        "CONFLUENCE_EMAIL": "your-email@example.com",
        "CONFLUENCE_API_TOKEN": "your-api-token-here"
      }
    }
  }
}

Or use environment variables:

{
  "mcp": {
    "confluence": {
      "type": "local",
      "command": ["npx", "-y", "@jsalamanc_01/mcp-confluence"],
      "enabled": true,
      "environment": {
        "CONFLUENCE_BASE_URL": "{env:CONFLUENCE_BASE_URL}",
        "CONFLUENCE_EMAIL": "{env:CONFLUENCE_EMAIL}",
        "CONFLUENCE_API_TOKEN": "{env:CONFLUENCE_API_TOKEN}"
      }
    }
  }
}

Usage

Once configured, you can use Confluence tools with OpenCode:

Search for all pages about "API" in Confluence. use confluence

Available Tools

Search Tools (3)

• search_confluence - Search Confluence content by keywords

  • Parameters: query (string), limit (number, default: 25)
  • Returns: List of matching pages with metadata

• get_confluence_spaces - List all available spaces

  • Parameters: limit (number, default: 25)
  • Returns: List of all Confluence spaces

• get_space_content - Get all pages in a space

  • Parameters: space_key (string), limit (number, default: 25)
  • Returns: List of pages in the specified space

Page Management Tools (6)

• get_confluence_page - Read a page by ID

  • Parameters: page_id (string)
  • Returns: Full page content with metadata

• create_confluence_page - Create a new page

  • Parameters: space_key (string), title (string), body (string), parent_page_id (optional)
  • Returns: Created page details with URL

• update_confluence_page - Update an existing page

  • Parameters: page_id (string), title (string), body (string), version_number (number)
  • Returns: Updated page details

• delete_confluence_page - Delete a page permanently

  • Parameters: page_id (string)
  • Returns: Success confirmation

Collaboration Tools (3)

• add_confluence_comment - Add a comment to a page

  • Parameters: page_id (string), comment_text (string)
  • Returns: Comment confirmation with details

• get_confluence_page_comments - Get all comments on a page

  • Parameters: page_id (string), limit (number, default: 25)
  • Returns: List of all comments with author and timestamp

• get_confluence_page_versions - Get version history

  • Parameters: page_id (string), limit (number, default: 25)
  • Returns: List of all versions with editor info

Attachments & Export Tools (2)

• get_confluence_page_attachments - List page attachments

  • Parameters: page_id (string), limit (number, default: 25)
  • Returns: List of files attached to the page

• export_confluence_page_html - Export page as HTML

  • Parameters: page_id (string)
  • Returns: HTML content of the page

Total: 14 tools

Examples

Search for pages

Find all documentation about database migrations using confluence

Create a page

Create a new page in the PROJ space titled "API Documentation" with installation instructions. use confluence

Update a page

Update the README page with the latest changes. use confluence

Delete a page

Delete the old migration guide page. use confluence

Add a comment

Add a comment to the API documentation page saying "Updated with v2 endpoints". use confluence

View page history

Show me the version history of the API documentation page. use confluence

Get all comments

Get all comments on the deployment guide page. use confluence

Export a page

Export the API documentation page as HTML. use confluence

Development

Local Setup

git clone https://github.com/jsalamanc/mcp-confluence.git
cd mcp-confluence
npm install
npm run build

Commands

# Watch for changes
npm run watch

# Run in development mode
npm run dev

# Build for production
npm run build

# Start the server
npm start

Project Structure

src/
├── index.ts                 # Entry point
├── server.ts               # MCP server implementation
├── confluence-client.ts    # Confluence API client with all methods
├── types.ts                # TypeScript types
└── tools/
    ├── page-tools.ts       # Page operations (read, create, update)
    ├── search-tools.ts     # Search operations
    └── advanced-tools.ts   # Advanced tools (delete, comments, versions, etc)

API Reference

The tools use the Confluence Cloud REST API v2.

Authentication

All requests are authenticated using HTTP Basic Auth with:

• Username: Your Confluence email
• Password: Your API token

Content Format

Page content uses Confluence's Storage Format (HTML-based markup):

<p>This is a paragraph</p>
<h1>This is a heading</h1>
<ul>
  <li>List item</li>
</ul>

Environment Variables

• CONFLUENCE_BASE_URL (required): Your Confluence instance URL (e.g., https://my-company.atlassian.net)
• CONFLUENCE_EMAIL (required): Your Confluence email address
• CONFLUENCE_API_TOKEN (required): Your Confluence API token

Troubleshooting

Authentication Error

• Verify your email and API token are correct
• Ensure the API token hasn't expired
• Check that the base URL doesn't have a trailing slash

Page Not Found

• Verify the page ID is correct
• Ensure you have access to the page
• Check that the page exists and hasn't been deleted

Publishing Error

• Verify the space key is correct
• Ensure you have write permissions to the space
• Check the HTML format of the body content

Performance

• Search operations are cached for 5 minutes
• Batch operations are limited to 25 items by default
• API calls have a 30-second timeout

Security

• Never commit your API tokens or credentials
• Use environment variables for sensitive data
• Regenerate tokens if they're exposed
• Restrict API token permissions to minimum required

Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

Roadmap

✅ Completed (v0.3.0)

• [x] Search pages
• [x] List spaces
• [x] Get space content
• [x] Read pages
• [x] Create pages
• [x] Update pages
• [x] Delete pages
• [x] Add comments
• [x] Get page comments
• [x] Get page versions/history
• [x] List page attachments
• [x] Export pages as HTML

🚀 Planned Features

• [ ] Upload attachments to pages
• [ ] Export pages to PDF
• [ ] Manage page permissions
• [ ] Work with page macros
• [ ] Batch operations
• [ ] Watch/subscribe to page changes
• [ ] Move pages between spaces
• [ ] Archive/restore pages

License

MIT

Support

For issues, questions, or suggestions:

• Open an issue on GitHub
• Check the documentation

Related Projects

• OpenCode - AI coding agent
• Model Context Protocol - Protocol specification
• Confluence Cloud API - Confluence API documentation

---

Made with ❤️ for the OpenCode community