Confluence MCP Server and API Client

This package provides a Model Context Protocol (MCP) server for Confluence Wiki and a standalone Confluence API client. It allows you to:

1. Use it as a JavaScript/Node.js library to interact with Confluence
2. Run it as an MCP server for Cursor IDE

Features

• Search Confluence Wiki pages
• Read page content and details
• Create new wiki pages
• Update existing wiki pages
• Insert Confluence modules (macros)
• List available spaces
• Manage page comments, attachments, and labels
• Handle page hierarchy and organization
• Create and manage content templates
• Export pages to different formats
• View page permissions and restrictions
• Seamless integration with Cursor IDE

Prerequisites

• Node.js 16 or higher
• Confluence API token
• Cursor IDE

Installation

As a dependency in your project

npm install mcp-confluence-fy

As a global CLI tool

npm install -g mcp-confluence-fy

No installation necessary (using npx)

npx mcp-confluence-fy

Usage

As a JavaScript Library

You can use this package as a regular JavaScript library to interact with Confluence:

import { createConfluenceClient } from 'mcp-confluence-fy';

// Create a Confluence client
const confluence = createConfluenceClient({
  host: 'https://your-confluence-instance.atlassian.net',
  username: 'your_username',
  password: 'your_api_token'
});

// Use the client to interact with Confluence
async function example() {
  // List spaces
  const spaces = await confluence.listSpaces(10);
  
  // Search for pages
  const searchResults = await confluence.searchWiki('your search query');
  
  // Get page information
  const pageInfo = await confluence.getPageInfo('123456');
  
  // Get page content
  const content = await confluence.getPageContent('123456', 'markdown');
  
  // Create a new page
  const newPage = await confluence.createPage({
    title: 'New Page Title',
    content: '# New Page\n\nThis is a new page created via the API.',
    spaceKey: 'SPACE',
    isMarkdown: true
  });
  
  // Update an existing page
  const updatedPage = await confluence.updatePage({
    pageId: '123456',
    title: 'Updated Title',
    content: '# Updated Page\n\nThis page has been updated.',
    isMarkdown: true
  });
  
  // Insert a Confluence macro/module
  const pageWithMacro = await confluence.insertModule({
    pageId: '123456',
    moduleName: 'info',
    moduleParams: {
      title: 'Information Macro',
      icon: 'true'
    },
    position: 'end' // 'start', 'end', or element ID
  });

  // Get page attachments
  const attachments = await confluence.getAttachments('123456');

  // Get page comments
  const comments = await confluence.getComments('123456');

  // Add a new comment to a page
  const comment = await confluence.addComment('123456', 'This is a new comment', true);

  // Work with labels
  const labels = await confluence.getPageLabels('123456');
  await confluence.addLabels('123456', ['important', 'documentation']);
  await confluence.removeLabel('123456', 'outdated');

  // Work with page hierarchy
  const pageTree = await confluence.getPageTree('123456', 3); // Get 3 levels of children
  await confluence.movePageToParent('123456', '789012'); // Move page to a new parent

  // Work with templates
  const template = await confluence.createTemplate(
    'SPACE', 
    'Meeting Notes', 
    '# Meeting Notes\n\n**Date:** \n**Participants:** \n\n## Agenda\n\n## Action Items',
    'Template for team meeting notes'
  );
  const spaceTemplates = await confluence.getSpaceTemplates('SPACE');

  // Export pages
  const pdfExport = await confluence.exportPageToPDF('123456');

  // Get space statistics
  const stats = await confluence.getSpaceContentStats('SPACE');

  // Get page permissions
  const restrictions = await confluence.getPageRestrictions('123456');

  // Get user information
  const userInfo = await confluence.getUserInfo('username');
}

As an MCP Server in your code

You can also create and start the MCP server programmatically:

import { createConfluenceServer } from 'mcp-confluence-fy';

// Create the server
const server = createConfluenceServer({
  host: 'https://your-confluence-instance.atlassian.net',
  username: 'your_username',
  password: 'your_api_token',
  port: 9001,
  useStdio: false // set to true for use with Cursor IDE
});

// Start the server
server.start()
  .then(() => {
    console.log('Server started successfully');
  })
  .catch(err => {
    console.error('Failed to start server:', err);
  });

As a CLI Tool

If installed globally, you can run the MCP server directly from the command line:

# Set environment variables
export CONFLUENCE_HOST="https://your-confluence-instance.atlassian.net"
export CONFLUENCE_USERNAME="your_username"
export CONFLUENCE_PASSWORD="your_api_token"

# Start the server with HTTP/SSE transport
mcp-confluence-fy

# Start the server with stdio transport (for Cursor IDE)
mcp-confluence-fy --stdio

Alternatively, you can create a .env file with these variables:

CONFLUENCE_HOST=https://your-confluence-instance.atlassian.net
CONFLUENCE_USERNAME=your_username
CONFLUENCE_PASSWORD=your_api_token
PORT=9001

Configuring with Cursor IDE

To use this MCP with Cursor, you have two options:

Option 1: Using npx (recommended)

Add the following to your Cursor configuration:

{
  "mcpServers": {
    "confluence": {
      "command": "npx",
      "args": [
        "-y",
        "mcp-confluence-fy",
        "--stdio"
      ],
      "env": {
        "CONFLUENCE_HOST": "https://your-confluence-instance.atlassian.net",
        "CONFLUENCE_USERNAME": "your_username",
        "CONFLUENCE_PASSWORD": "your_api_token"
      }
    }
  }
}

This will automatically download and run the latest version of mcp-confluence-fy without requiring installation.

Option 2: Using an installed version

1. Install the package globally: npm install -g mcp-confluence-fy
2. Add the following to your Cursor configuration:

{
  "mcpServers": {
    "confluence": {
      "command": "mcp-confluence-fy",
      "args": ["--stdio"],
      "env": {
        "CONFLUENCE_HOST": "https://your-confluence-instance.atlassian.net",
        "CONFLUENCE_USERNAME": "your_username",
        "CONFLUENCE_PASSWORD": "your_api_token"
      }
    }
  }
}

Available Methods

The Confluence client provides these methods:

• getPageContent(pageId, format) - Get content from a specific page
• searchWiki(query, limit) - Search for Confluence pages
• getPageInfo(pageId) - Get detailed information about a page
• createPage({ title, content, spaceKey, parentId, isMarkdown }) - Create a new page
• updatePage({ pageId, title, content, isMarkdown }) - Update an existing page
• listSpaces(limit, type) - List available Confluence spaces
• insertModule({ pageId, moduleName, moduleParams, position }) - Insert a Confluence macro
• getAttachments(pageId, limit) - Get attachments from a page
• getComments(pageId, limit) - Get comments from a page
• addComment(pageId, content, isMarkdown) - Add a comment to a page
• getPageLabels(pageId) - Get labels from a page
• addLabels(pageId, labels) - Add labels to a page
• removeLabel(pageId, labelName) - Remove a label from a page
• getPageTree(rootPageId, depth) - Get page hierarchy tree
• movePageToParent(pageId, newParentId) - Move a page to a new parent
• createTemplate(spaceKey, name, content, description, isMarkdown) - Create a content template
• getSpaceTemplates(spaceKey, limit) - Get templates from a space
• exportPageToPDF(pageId, expand) - Generate PDF export URL
• getSpaceContentStats(spaceKey) - Get content statistics for a space
• getPageRestrictions(pageId) - Get page permissions
• getUserInfo(username) - Get information about a user

Available MCP Tools for Cursor IDE

The MCP server provides these specialized tools optimized for Cursor IDE:

• mcp_confluence_search_wiki - Search for recent pages in Confluence Wiki
• mcp_confluence_get_wiki_content - Get content from a Confluence Wiki page
• mcp_confluence_create_page - Create a new page with built-in space selection
• mcp_confluence_update_page - Update an existing page with helpful guidance
• mcp_confluence_get_page_info - Get detailed information about a page
• mcp_confluence_list_spaces - List all available spaces in Confluence
• mcp_confluence_get_space - Get detailed information about a specific space
• mcp_confluence_get_space_content - Get list of content from a specific space
• mcp_confluence_get_attachments - Get formatted list of page attachments
• mcp_confluence_get_comments - Get formatted list of page comments
• mcp_confluence_add_comment - Add a comment to a page
• mcp_confluence_get_page_tree - Get nicely formatted page hierarchy
• mcp_confluence_get_page_labels - Get labels from a page
• mcp_confluence_add_labels - Add labels to a page
• mcp_confluence_remove_label - Remove a label from a page
• mcp_confluence_move_page - Move a page to a new parent
• mcp_confluence_create_template - Create a content template
• mcp_confluence_get_space_templates - Get templates from a space
• mcp_confluence_export_page_to_pdf - Generate PDF export URL
• mcp_confluence_get_page_restrictions - Get page permissions
• mcp_confluence_get_user_info - Get information about a user
• mcp_confluence_insert_module - Insert a Confluence module/macro into a page

Development

To run the server in development mode with auto-reload:

git clone https://github.com/fuyoukache/mcp-confluence-fy.git
cd mcp-confluence-fy
npm install
npm run dev

License

ISC

Credits

Built using the Model Context Protocol and Confluence.js API client.