ronnysuero/confluence-mcp-server

Confluence MCP Server for Cursor

This project provides a Managed Component Provider (MCP) server that allows Cursor to access and use documentation from a Confluence space as a context source (@).

The server connects to the Confluence API, downloads all pages from a specific space, processes them, and exposes them through the /list and /get endpoints required by Cursor.

Features

• Local Synchronization: Downloads and saves Confluence content locally for fast and efficient access.
• MCP-Compatible API: Implements the /list and /get endpoints required by Cursor.
• Easy Configuration: Uses environment variables to manage credentials securely.
• Network Access: Can be run on a server machine to provide access to multiple users on the same network.

Installation and Usage Guide

Follow these steps to clone, configure, and run the server.

1. Clone the Repository

First, clone this repository to your local machine.

git clone https://github.com/ronnysuero/confluence-mcp-server
cd confluence-mcp-server

2. Create and Activate a Virtual Environment

It is a best practice to use a Python virtual environment to isolate project dependencies.

# Create the virtual environment
python -m venv venv

# Activate on Windows (CMD/PowerShell)
.\venv\Scripts\activate

# Activate on macOS/Linux
source venv/bin/activate

3. Install Dependencies

Install all the necessary libraries listed in requirements.txt.

pip install -r requirements.txt

4. Configure Credentials

The server needs your Confluence credentials to function.

1. Create a .env file: Copy the .env.example template to create your own configuration file.

   # On Windows
   copy .env.example .env
   
   # On macOS/Linux
   cp .env.example .env
   

2. Edit the .env file: Open the .env file with a text editor and fill in the following variables:

   • CONFLUENCE_URL: The base URL of your Confluence instance (e.g., https://your-company.atlassian.net).
   • CONFLUENCE_USERNAME: Your Atlassian account email.
   • CONFLUENCE_API_TOKEN: An API Token generated from your account. Do not use your password. You can create one here.
   • CONFLUENCE_SPACE_KEY: The key of the Confluence space you want to sync (e.g., DOCS, PROJECT). You can find it in the space URL (/spaces/KEY/).

Running the Server

Once configured, you can start the server.

Local Execution (For your machine only)

uvicorn src.main:app --reload

Network Execution (To access from other machines)

To allow Cursor (or other machines on your network) to connect, start the server with the host set to 0.0.0.0.

uvicorn src.main:app --host 0.0.0.0 --port 8000

Firewall Note: If you run the server in network mode, you may need to create an inbound rule in the host machine's firewall to allow incoming connections on port 8000.

Synchronizing the Documentation

Before Cursor can use the documentation, you must synchronize it.

1. Keep the server running.

2. Open a new terminal and run the following command to start the download process:

   curl -X POST http://127.0.0.1:8000/sync
   

   If the server is on another machine, replace 127.0.0.1 with that machine's IP address.

3. In the terminal where the server is running, you will see the synchronization progress. This process may take several minutes. The files will be saved in the data/ folder.

Connecting with Cursor

With the server running and the data synchronized, you can now connect it to Cursor.

1. Open the Command Palette in Cursor (Ctrl+Shift+P on Windows/Linux, Cmd+Shift+P on Mac).

2. Type "Docs: Add a new doc source" and select it.

3. Alternatively, type @ in the chat panel and click the "Add a new doc..." button at the bottom of the pop-up.

4. Select the source type "Managed Component Provider (MCP)".

5. In the URL field, enter the address of your server's /list endpoint:

   • If the server is running on your same machine:

     http://127.0.0.1:8000/list
     

   • If the server is running on another machine in your network:

     http://<IP_OF_THE_SERVER_MACHINE>:8000/list
     

     (Example: http://192.168.1.105:8000/list)

That's it! You can now use @ in Cursor to search for and add context from your Confluence documentation.