Confluence SSO MCP

A Model Context Protocol (MCP) server for Atlassian Confluence. It connects Cursor, Claude Desktop, and other MCP clients to whatever Confluence site you configure—your company’s Data Center, a Cloud site (*.atlassian.net), or any host where the Confluence REST API is available and you can authenticate.

See also (sibling projects)

What this project does

Teams often use SSO (SAML, OIDC, etc.) or strict API policies. This server is not tied to one vendor or tenant: you set CONFLUENCE_BASE_URL to your environment.

• Optional Personal Access Token (PAT) or API token — When your site supports it, set one in MCP config; the server sends Authorization: Bearer on each request.
• Browser SSO via cookies — If you have no PAT, or the API returns 401/403, you can complete login in a real browser (Playwright). The session is saved and reused for REST calls.
• Same tools everywhere — Once configured, assistants use MCP tools (search, get page, create page, attachments, etc.) against your base URL.

Typical uses: documentation Q&A in the IDE, drafting or updating pages from chat, finding pages by CQL, pulling diagrams or attachment metadata for review.

Scope: Standard Confluence REST paths (/rest/api/...). Use the root URL your organization uses (include /wiki in the path only if your instance requires it). If you run multiple Confluence deployments, add one MCP server block per site, each with its own CONFLUENCE_BASE_URL, and use confluence_health_check if page IDs mismatch between browser and API.

How it works (short)

1. The MCP client (e.g. Cursor) starts this Node process and talks over stdio (standard input/output) using the MCP protocol.
2. The server implements tool handlers that call Confluence’s REST API (node-fetch, with PAT or Cookie header).
3. Auth: Prefer PAT if configured → on 401/403, retry with saved SSO cookies if confluence_login (or npm run login) was run.
4. SSO login opens Chromium (Playwright), you sign in as usual; cookies are stored under cookies/session.json (local, gitignored).

[ Cursor / MCP client ] --stdio--> [ this server ] --HTTPS--> [ Confluence REST API ]
                                        |
                                        +-- PAT and/or cookies/session.json

Prerequisites

Quick start

1. Install dependencies (from a clone) or use npx (see below).
2. Set CONFLUENCE_BASE_URL (and optionally CONFLUENCE_PAT) in your MCP client config—usually %USERPROFILE%\.cursor\mcp.json on Windows.
3. Restart the MCP client after editing config.
4. Either set a PAT or run confluence_login / npm run login once so cookies exist for SSO.
5. In Agent chat (or equivalent), use the Confluence tools (search, get page, etc.).

Installation

Option A — Published package (npx)

Use the exact package name from npm (see your package.json name field). Example:

# One-time: Chromium for SSO browser login
npx playwright install chromium

# Run the MCP on stdio (set base URL first)
# Windows CMD:
set CONFLUENCE_BASE_URL=https://confluence.example.com
npx -y confluence-sso-mcp

# Windows PowerShell:
$env:CONFLUENCE_BASE_URL="https://confluence.example.com"
npx -y confluence-sso-mcp

Option B — Clone this repository

git clone <your-repo-url>
cd confluence-mcp-oauth
npm install
npm run install-browser   # Chromium for SSO
npm start                 # runs the MCP on stdio; usually Cursor starts this for you

Configuration

Where settings live

• Primary: Cursor global MCP file: %USERPROFILE%\.cursor\mcp.json (Windows) or ~/.cursor/mcp.json (macOS/Linux).
• Server block name: You can name the entry anything (e.g. confluence, docs-internal, confluence-prod). This project discovers the correct env by matching args to this package’s src/index.js path, with fallback to legacy keys confluence-sso and mywiki-sso for older configs.
• PAT: Put CONFLUENCE_PAT (or CONFLUENCE_API_TOKEN) only in mcp.json env—not in the project .env (those keys are ignored in .env by design).

Environment variables

Optional non-secret overrides can go in a local .env in this repo (see .env.example); do not put CONFLUENCE_PAT or CONFLUENCE_API_TOKEN there.

Multiple Confluence instances (same clone path): In mcp.json, give each server its own CONFLUENCE_BASE_URL. Add CONFLUENCE_MCP_SERVER_KEY matching the server id (see table). Without this, the first matching block in the file could be used for fill-in merge when a variable is unset—never for URL once Cursor has already set it (see code: process env is not overwritten).

Configuration reference (files & precedence)

Authentication order

1. If a PAT is set, requests use Bearer authentication first.
2. If the response is 401 or 403 and cookies/session.json exists, the same request is retried with the cookie session.
3. If no PAT is configured, only cookies are used.
4. If neither works, tools fail until you add a PAT or complete confluence_login.

Cursor: mcp.json examples

Restart Cursor after changes.

Using npx (published package)

Package name on npm: confluence-sso-mcp.

{
  "mcpServers": {
    "confluence-sso": {
      "command": "npx",
      "args": ["-y", "confluence-sso-mcp"],
      "env": {
        "CONFLUENCE_BASE_URL": "https://confluence.company.com",
        "CONFLUENCE_LOGIN_WAIT_SECONDS": "90",
        "CONFLUENCE_PAT": "your-personal-access-or-api-token"
      }
    }
  }
}

Using a local clone (node + path)

args must contain the full path to src/index.js so npm run login can resolve the same settings from mcp.json.

{
  "mcpServers": {
    "confluence-sso": {
      "command": "node",
      "args": ["C:/path/to/confluence-mcp-oauth/src/index.js"],
      "env": {
        "CONFLUENCE_BASE_URL": "https://confluence.company.com",
        "CONFLUENCE_LOGIN_WAIT_SECONDS": "90",
        "CONFLUENCE_PAT": "your-personal-access-or-api-token"
      }
    }
  }
}

Repository / homepage URLs in package.json may point to a template GitHub path—update them for your fork if needed.

Day-to-day usage

First-time SSO login (same behavior everywhere)

• Cursor Agent: run the confluence_login tool.
• Terminal: npm run login from the package directory (reads mcp.json via config.js).
• VS Code / Cursor task: Tasks: Run Task → Confluence: SSO login (save cookies) (if configured in .vscode/tasks.json).

Cookies are stored in cookies/session.json (gitignored).

MCP tools (reference)

Read & search

Write (needs Confluence permissions)

Body format: storageHtml must be Confluence storage HTML/XML (e.g. <p>Hello</p>), not arbitrary wiki markup unless your instance accepts it.

Validation

Security

• Treat PATs like passwords; keep them in mcp.json (or your secret store), not in git or public .env files.
• Cookies are as powerful as your browser session—protect the directory that contains cookies/.
• Edits in Confluence are still attributed and audited like normal UI edits—follow your organization’s policies and compliance rules.

Troubleshooting

For broader Cursor MCP issues, see Cursor forum: MCP tools.

License and repository

See package.json for repository, homepage, and bugs links once you publish or fork.

The npm package name is confluence-sso-mcp (unscoped). If you previously published under @svasimahmed283/confluence-sso-mcp, keep that version for backward compatibility or deprecate it on npm after publishing this name.