Confluence MCP Server Cursor IDE Setup (2025-2026)

How do you set up the Confluence MCP server in Cursor IDE? Generate an Atlassian API token, add a confluence block to ~/.cursor/mcp.json with your site URL, email, and token, then restart Cursor. Once connected, Cursor can search, read, and write Confluence pages directly from chat — no separate login or browser tab required, and no OAuth app registration for this token-based route. This is the Confluence-only guide — the config and tool set below haven't changed between the 2025 and 2026 Cursor release lines, so a 2025-dated tutorial's field names still load correctly today.

Confluence is where your team documents everything — architecture decisions, runbooks, project specs. The Confluence MCP server lets Cursor IDE read and write to your Confluence spaces without leaving your editor. This guide covers the full setup, current through both the 2025 and 2026 Cursor release lines (the token flow and env variable names below haven't changed between them), plus where it fits if you're already running the combined Atlassian server.

Scope check: this page is Confluence pages and spaces only — search, read, write, attachments. It is not the Jira ticket-tracking guide. If your actual goal is pulling sprint tickets or transitioning issues rather than documents, the Jira MCP server guide is the one you want; it uses the same underlying Atlassian API token but covers a completely different set of tools.

Quick Reference

| | |
|---|---|
| Auth method | Atlassian API token (not your account password) |
| Config keys | CONFLUENCE_BASE_URL, CONFLUENCE_USERNAME, CONFLUENCE_API_TOKEN |
| Package | confluence-mcp-server (community) or @atlassian/mcp-confluence |
| Content format on write | ADF (Atlassian Document Format), not markdown |
| Search syntax | Plain text or raw CQL |
| Setup time | ~10 minutes |
| Covers | Confluence pages/spaces only — not Jira tickets (see Jira guide) |

What the Confluence MCP Server Does

With the Confluence MCP server connected to Cursor, you can:

This is especially powerful when writing code that needs to match documented architecture — your AI has context, not just your local files.

Under the hood, most confluence-mcp-server builds wrap Confluence Cloud's REST API v2 (/wiki/api/v2/pages, /spaces, /search) rather than the older v1 endpoints, and search tools typically accept raw CQL (Confluence Query Language) alongside plain-text queries — so a prompt like "find pages in ENG modified in the last 30 days labeled 'runbook'" can compile down to a proper space = ENG AND label = "runbook" AND lastmodified > now("-30d") query instead of a fuzzy text match. If your searches keep returning noise, ask Cursor to show you the CQL it generated before running it — that's usually where the mismatch is.

The Content Format Gotcha: ADF, Not Markdown

This is the detail that trips people up on their first write operation. Confluence Cloud doesn't store page bodies as markdown or raw HTML — it uses Atlassian Document Format (ADF), a structured JSON tree. When you ask Cursor to "create a page documenting the webhook service," the MCP server has to convert whatever it generates into ADF (or the older XHTML-based "storage format," which Confluence still accepts on write and converts internally) before the API will accept it.

In practice this mostly works — the server handles the conversion — but two things commonly go sideways: complex nested lists or tables sometimes flatten into plainer structures than what you'd get hand-authoring in the Confluence editor, and Confluence-specific macros (status badges, expand panels, Jira issue macros embedded in a page) generally can't be generated from a markdown-style prompt at all, since there's no markdown equivalent for a macro node. If a generated page looks structurally "off" compared to a page a human wrote directly in Confluence, ADF conversion — not a bug in your config — is almost always why.

Prerequisites

Before you start, make sure you have:

Step 1: Generate Your Confluence API Token

1. Log into your Atlassian account at id.atlassian.com
2. Click your profile avatar → Manage account
3. Go to Security → Create and manage API tokens
4. Click Create API token
5. Label it something like cursor-mcp-2026
6. Copy the token — you won't see it again

Your base URL will be your Atlassian domain: https://yourcompany.atlassian.net

For token security basics — rotation, scoping, and where not to store them — see how to authenticate MCP servers with OAuth and API keys.

Step 2: Install the Confluence MCP Server

The recommended package is @atlassian/mcp-confluence or the community confluence-mcp-server. Install globally:

npm install -g @modelcontextprotocol/server-confluence

Or use the Atlassian-maintained version:

npm install -g confluence-mcp-server

Test the installation:

confluence-mcp-server --help

Step 3: Configure Cursor IDE

Open Cursor's MCP settings. Go to Settings → MCP (or press Cmd+Shift+P → "Open MCP Settings").

Add the Confluence server to your mcp.json config:

{
  "mcpServers": {
    "confluence": {
      "command": "npx",
      "args": ["-y", "confluence-mcp-server"],
      "env": {
        "CONFLUENCE_BASE_URL": "https://yourcompany.atlassian.net",
        "CONFLUENCE_USERNAME": "your-email@company.com",
        "CONFLUENCE_API_TOKEN": "your-api-token-here",
        "CONFLUENCE_SPACE_KEY": "ENG"
      }
    }
  }
}

Replace the values with your actual credentials. CONFLUENCE_SPACE_KEY is optional — omit it to access all spaces.

Step 4: Verify the Connection

Restart Cursor after saving the config. In the chat panel, type:

List my Confluence spaces

Or:

Search Confluence for "deployment process"

If Cursor returns real results from your knowledge base, you're connected.

Step 5: Real-World Usage Patterns

Pull context before writing code

Before I write the authentication module, find the auth architecture doc in Confluence and summarize the key decisions

Generate and push documentation

I just finished building the webhook service. Create a Confluence page in the ENG space called "Webhook Service Architecture" documenting how it works based on the code in /src/webhooks/

Cross-reference specs

Find the product spec for the checkout flow in Confluence and compare it against the current implementation in /src/checkout/

Update runbooks

Update the "Deployment Runbook" page in Confluence to include the new environment variable FEATURE_FLAG_API_KEY that we added today

Troubleshooting Common Issues

"Authentication failed" error
Double-check your API token was copied correctly with no trailing spaces. Also verify your username is the email address tied to your Atlassian account, not a display name.

"Space not found" error
Your space key needs to match exactly. Find it in Confluence under Space Settings → Space Details. It's usually all caps like ENG, PROD, or WIKI.

"Rate limit exceeded"
Confluence Cloud rate limits API calls. If you're hitting limits, add a small delay between bulk operations or upgrade to a higher Atlassian tier.

MCP server not showing in Cursor
Make sure Node.js is in your PATH. Run which node in terminal to verify. If Cursor launched before Node was installed, fully restart it. For a broader checklist that applies beyond just this integration, see debugging MCP server issues in Cursor.

A generated page looks garbled or lost its formatting
See the ADF section above — this is almost always the markdown-to-ADF conversion dropping a nested structure or hitting a macro it can't reproduce, not a connection failure. Re-run the write with a simpler structure (flatten nested lists, skip macros) if the output needs to match a specific layout exactly.

"Version conflict" or "page has been updated" error on write
Confluence versions every page, and the update API call expects the version number it last read. If someone (or another Cursor session) edited the page between your read and your write, the server's cached version number is stale and the write is rejected rather than silently overwritten. Ask Cursor to re-fetch the page immediately before retrying the update — don't reuse a page object from earlier in a long chat session.

Attachment upload fails or silently drops the file
Confluence Cloud caps individual attachment size (commonly 100MB on standard plans, lower on some legacy tiers), and the MCP write tools generally handle text and small images fine but aren't built for large binary uploads — a failed upload on a large file is usually a size-limit rejection from the API, not a broken config. For anything beyond a few MB, upload through the Confluence UI directly and let Cursor reference the resulting attachment by name instead.

Beyond installation issues, treat the API token itself as a credential worth protecting the same way you'd protect a database password — see our MCP security best practices for 2026 for guidance on scoping tokens and avoiding accidental exposure in shared configs.

Using with Jira MCP Together

Confluence and Jira work best together. If you've already set up the Jira MCP server, you can chain them:

Find the Jira ticket PROJ-1234, read the attached Confluence spec, then implement the feature described

This gives Cursor full context: the ticket requirements plus the detailed spec — exactly what a senior dev would read before coding. The same pull-based pattern works well with Notion MCP if part of your team keeps specs there instead of Confluence — you're not limited to a single documentation source per session.

Advanced: Atlassian MCP Bundle

Atlassian maintains a unified MCP server that covers Jira, Confluence, and Bitbucket in one package. See the Atlassian MCP setup guide for instructions on running all three from a single config entry.

Token-Based Server vs. the Official OAuth Bundle: Which Should You Actually Run?

There are two legitimate ways to get Confluence into Cursor, and this guide only covers one of them in depth. Here's the actual trade-off:

The practical downside of the OAuth bundle for a docs-only user: it's an all-or-nothing grant. You can't authorize "just Confluence" through the official server the way you can scope a personal API token to a single product. If you want the narrowest possible credential, or your org's security policy prefers named, individually-revocable tokens over a shared OAuth app, stick with the token-based setup in this guide.

Restricting Access to Specific Spaces

CONFLUENCE_SPACE_KEY in the config above only accepts one value — there's no supported syntax for a comma-separated list of spaces in a single server entry. If you need Cursor to search "ENG" for your own team's docs but explicitly not "HR" or "FINANCE," the working pattern is one server entry per space, each under a distinct key:

{
  "mcpServers": {
    "confluence-eng": {
      "command": "npx",
      "args": ["-y", "confluence-mcp-server"],
      "env": {
        "CONFLUENCE_BASE_URL": "https://yourcompany.atlassian.net",
        "CONFLUENCE_USERNAME": "your-email@company.com",
        "CONFLUENCE_API_TOKEN": "your-api-token-here",
        "CONFLUENCE_SPACE_KEY": "ENG"
      }
    },
    "confluence-product": {
      "command": "npx",
      "args": ["-y", "confluence-mcp-server"],
      "env": {
        "CONFLUENCE_BASE_URL": "https://yourcompany.atlassian.net",
        "CONFLUENCE_USERNAME": "your-email@company.com",
        "CONFLUENCE_API_TOKEN": "your-api-token-here",
        "CONFLUENCE_SPACE_KEY": "PRODUCT"
      }
    }
  }
}

This is also the only real access control this integration gives you — the API token itself is scoped to whatever the underlying Atlassian account can see, not to CONFLUENCE_SPACE_KEY. The space key filters what a given server entry searches by default; it does not enforce a hard permission boundary. If the account behind the token can technically read HR's space in the Confluence UI, a differently-configured server entry (or a stray query without the key set) can still surface it. Don't rely on this as a security control — use a restricted-permission Atlassian account for that.

Summary

The Confluence MCP integration turns your documentation from a read-only reference into an active part of your development workflow. Cursor can now search, read, and write Confluence pages as part of any coding task — closing the gap between what's documented and what's built.

Setup takes about 10 minutes. The main requirement is an API token with appropriate space permissions. Once connected, the most common use case is having Cursor pull spec docs before writing features — which alone saves significant back-and-forth.

Frequently Asked Questions

Q: What's the fastest confluence MCP server cursor IDE setup path for 2026?
A: Three things, in order: generate an Atlassian API token, add the confluence block above to ~/.cursor/mcp.json with your site URL, email, and token, then restart Cursor. No local database, no OAuth app registration, no admin approval needed for a personal API token — most people are searching Confluence from Cursor chat inside 10 minutes.

Q: Do I need the full Atlassian MCP server, or is a dedicated Confluence server enough?
A: If you only need docs (no Jira ticket access), the dedicated Confluence server in this guide is lighter — one config block, one token scoped to Confluence. If your team also wants Cursor to read and update Jira tickets, the Atlassian MCP bundle covers Jira, Confluence, and Bitbucket from a single server entry instead of running two separate connections.

Q: Can Cursor create a new Confluence page, or only edit existing ones?
A: Both. The write tools support creating a brand-new page under a specified space (and optionally a parent page for hierarchy) as well as updating the body of an existing page. New pages default to draft status in some Confluence configurations, so check your space's permissions if a generated page doesn't show up where you expect.

Q: Does this work with Confluence Data Center, or only Confluence Cloud?
A: Cloud is the primary supported target and what most setups use. Data Center works if your instance exposes the same REST API surface and your token/auth method is compatible, but expect more variance — test with a read-only search before relying on write operations against an on-prem instance.

Q: My Cursor searches return no results even though the pages exist.
A: This is almost always a space-scoping issue, not a broken connection. If CONFLUENCE_SPACE_KEY is set in your config, Cursor only searches that one space — remove it to search everything, or confirm the key matches exactly (space keys are case-sensitive and usually all caps).

Q: Is there a faster way to keep Confluence and code in sync without asking every time?
A: Not automatically — this integration is pull-based (you ask, Cursor fetches), not a live sync. For docs that change often, the more reliable workflow is asking Cursor to re-check the source page at the start of a session rather than trusting a summary from earlier in the conversation, since Confluence content can change between chats.

Q: What's the complete Confluence MCP server Cursor IDE setup process for 2026, in order?
A: Generate an Atlassian API token, install the confluence-mcp-server package (or let npx fetch it on first run), add the confluence block to ~/.cursor/mcp.json with your base URL, email, and token, then restart Cursor and confirm with a read-only prompt like "List my Confluence spaces." That's the whole setup — no separate OAuth app registration is needed for this token-based route.

Q: Can I limit Cursor to searching only one Confluence space instead of my whole site?
A: Yes, set CONFLUENCE_SPACE_KEY to that space's key. It only accepts a single value per server entry, though — if you need Cursor scoped to two or three specific spaces and explicitly excluded from others, run one server entry per space under different keys rather than trying to list multiple spaces in one entry.

Q: I searched for "confluence mcp server cursor ide setup 2026" — is this different from the Jira guide?
A: Yes, distinctly. This page covers Confluence spaces and pages — search, read, write, attachments. The Jira guide covers tickets, sprints, and transitions. Both can run off the same Atlassian API token, but the tools and workflows on each page don't overlap — read whichever guide matches what you're actually trying to do, not just which Atlassian product name you typed.

Q: Does the Confluence MCP server setup change between Cursor's 2025 and 2026 releases?
A: No. The confluence-mcp-server package and the CONFLUENCE_BASE_URL / CONFLUENCE_USERNAME / CONFLUENCE_API_TOKEN env variable names in this guide are unchanged across recent Cursor versions — a config written against a 2025 tutorial still loads correctly in 2026 builds.

Q: Why does a Confluence page Cursor generated look structurally different from one I'd write by hand?
A: Confluence Cloud stores page bodies in Atlassian Document Format (ADF), not markdown or raw HTML. The MCP server converts generated content into ADF (or storage format) before writing it, and that conversion can flatten complex nested tables or lists, and can't reproduce Confluence-specific macros like status badges or expand panels — there's no markdown equivalent for a macro node. This is expected behavior, not a broken config.

Q: Can the Confluence MCP server run real CQL (Confluence Query Language) searches, or only plain-text search?
A: Most confluence-mcp-server builds accept both — a plain-text prompt gets compiled into a CQL query behind the scenes, and you can also hand it CQL directly (e.g. space = ENG AND label = "runbook"). If a search returns unexpected results, ask Cursor to show the CQL it generated before running it; that's the fastest way to spot a scoping mistake.

Q: What's the exact confluence mcp server cursor ide setup 2026 process, in order?
A: Generate an Atlassian API token (Step 1), install confluence-mcp-server or let npx fetch it (Step 2), add the confluence block to mcp.json with CONFLUENCE_BASE_URL, CONFLUENCE_USERNAME, and CONFLUENCE_API_TOKEN (Step 3), restart Cursor, then confirm with "list my Confluence spaces" (Step 4). No OAuth app registration needed for this token-based route — that's the full setup.

Q: I'm pulling architecture diagrams from a whiteboard tool, not just Confluence docs — does that need a separate connection?
A: Yes. Confluence MCP covers text pages and spaces; it doesn't read visual boards. If your team keeps system diagrams in a tool like Miro, the Miro MCP server is a separate connection — pairing both lets Cursor pull a written spec from Confluence and a diagram from Miro in the same session.

Q: Why did my page update get rejected with a version conflict error?
A: Confluence versions every page, and an update call must include the version number the server last read. If the page changed since then — a teammate edited it, or an earlier tool call in the same session read a now-stale copy — the write is rejected rather than silently overwriting the newer edit. Ask Cursor to re-fetch the page immediately before retrying, rather than reusing a page object from earlier in a long conversation.

Q: Is there a file size limit on attachments Cursor can upload to a Confluence page?
A: Yes, effectively the same limit Confluence Cloud enforces for any upload — commonly around 100MB on standard plans, lower on some legacy tiers. The write tools handle text and small images without issue, but a large binary upload failing is almost always this size limit, not a broken connection. Upload large files through the Confluence UI directly and have Cursor reference the resulting attachment by name.

Q: Does the "confluence mcp server cursor ide setup" process work the same in 2025 and 2026 Cursor builds?
A: Yes — this is a 2025-2026 guide because nothing in the setup changed between those release lines. The confluence-mcp-server package name and the CONFLUENCE_BASE_URL / CONFLUENCE_USERNAME / CONFLUENCE_API_TOKEN env variables are the same whether you're following a screenshot from a 2025 tutorial or setting this up fresh today.

Related Guides

---