Motivation

As a daily Cursor IDE user, I'm always looking for ways to enhance my development workflow by integrating the tools and services I use most frequently. Confluence has been an essential part of my documentation workflow, and I wanted to access it directly from within Cursor. Building an MCP server seemed like the perfect opportunity to not only integrate Confluence but also gain hands-on experience with the MCP protocol.

The ability to query Confluence pages, create content, and manage spaces directly from my IDE would streamline my documentation process significantly. Plus, implementing an MCP server would help me better understand the protocol's architecture and best practices.

Implementation

Let's walk through building a production-ready MCP server for Confluence integration. We'll create a TypeScript implementation that handles authentication and common Confluence operations.

Project Structure

First, let's set up our project structure:

mcp-server/
├── src/
│   ├── server.ts
│   ├── main.ts
│   └── types/
│       └── confluence.ts
├── package.json
├── tsconfig.json
└── .env

Installing Dependencies

Create a new project and install the required dependencies:

npm init -y
npm install @cursor/mcp-api axios dotenv zod typescript

Add the following to package.json:

{
  "name": "confluence-mcp-server",
  "version": "1.0.0",
  "scripts": {
    "build": "tsc",
    "start": "node dist/main.js"
  }
}

Environment Configuration

Create a .env file for Confluence credentials:

CONFLUENCE_HOST=https://your-domain.atlassian.net
CONFLUENCE_TOKEN=your-api-token

Server Implementation

Let's implement the server in src/server.ts:

import { MCPServer } from '@cursor/mcp-api';
import axios from 'axios';
import { z } from 'zod';

// Environment validation
const envSchema = z.object({
  CONFLUENCE_HOST: z.string().url(),
  CONFLUENCE_TOKEN: z.string().min(1),
});

const env = envSchema.parse(process.env);

// Create Axios client
const client = axios.create({
  baseURL: `${env.CONFLUENCE_HOST}/wiki/api/v2`,
  headers: {
    'Authorization': `Bearer ${env.CONFLUENCE_TOKEN}`,
    'Content-Type': 'application/json',
  }
});

// Create MCP server
export const server = new MCPServer();

// Add tools
server.tool({
  name: 'get_page',
  description: 'Get a Confluence page by ID',
  parameters: z.object({
    pageId: z.string().describe('The ID of the page to retrieve'),
  }),
  handler: async ({ pageId }) => {
    const response = await client.get(`/pages/${pageId}`);
    return response.data;
  }
});

server.tool({
  name: 'search_pages',
  description: 'Search Confluence pages',
  parameters: z.object({
    query: z.string().describe('Search query'),
    limit: z.number().optional().default(10),
  }),
  handler: async ({ query, limit }) => {
    const response = await client.get('/pages', {
      params: { query, limit }
    });
    return response.data;
  }
});

server.tool({
  name: 'create_page',
  description: 'Create a new Confluence page',
  parameters: z.object({
    spaceId: z.string().describe('Space ID'),
    title: z.string().describe('Page title'),
    content: z.string().describe('Page content in storage format'),
  }),
  handler: async ({ spaceId, title, content }) => {
    const response = await client.post('/pages', {
      spaceId,
      title,
      body: {
        representation: 'storage',
        value: content
      }
    });
    return response.data;
  }
});

Entry Point

Create src/main.ts:

import { server } from './server';

async function main() {
  await server.listen(3000);
  console.log('Confluence MCP server running on port 3000');
}

main().catch(console.error);

Usage

Let's set up the Confluence MCP server in Cursor IDE.

Installation

Install the package globally:

npm install -g confluence-mcp-server

Configuration

Add the following to your Cursor IDE's mcp.json:

{
  "servers": [
    {
      "name": "confluence",
      "command": "confluence-mcp-server",
      "env": {
        "CONFLUENCE_HOST": "https://your-domain.atlassian.net",
        "CONFLUENCE_TOKEN": "your-api-token"
      }
    }
  ]
}

Example Prompts

Here are some example prompts you can use in Cursor:

1. Search for pages about a specific topic:

Find all Confluence pages about "kubernetes deployment"

2. Get details about a specific page:

Show me the content of Confluence page with ID "123456"

3. Create a new page:

Create a new Confluence page in space "TEAM" titled "Sprint Planning" with meeting notes

How It Works

Here's a sequence diagram showing how the Confluence MCP server integrates with Cursor IDE:

Rendering diagram...

The MCP server acts as a bridge between Cursor IDE and the Confluence API, handling authentication and translating natural language requests into API calls. When you make a request in Cursor, it's routed to the appropriate tool in the MCP server, which then makes the corresponding API call to Confluence. The response is processed and returned to Cursor, where it can be used to generate helpful responses.