Confluence MCP Server

A Model Context Protocol (MCP) server that connects AI agents to Confluence Cloud. Agents can search, read, create, and update Confluence content — pages, comments, links, images, and labels.

The agent authenticates via Atlassian OAuth 2.0 and passes its Bearer token to the server on each request — no credentials are stored on the server, and every caller acts as their own Confluence user (respecting their existing permissions).

Runs as a portable streamable-HTTP server — deploy with Docker to Azure Container Apps, App Service, or any container host, and connect from Microsoft Copilot Studio, VS Code (GitHub Copilot), or any MCP-compatible client.

ℹ️ A token mode is also available for local development / single-user self-hosting — see Local development.

---

What it does — the tools

Tool	Description	Type
search_pages	Find pages by keyword (filters: space, created/modified dates, label)	Read
get_page	Read a single page's content	Read
get_page_context	One-shot: page + comments + links + images	Read
search_page_content	Find text inside one page, with context	Read
get_comments	List comments and replies (incl. their images)	Read
search_comments	Find comments matching a phrase (one page or site-wide)	Read
extract_links	List hyperlinks on a page and/or in its comments	Read
get_images	List images on a page and/or in its comments (source-tagged)	Read
get_labels	List a page's labels	Read
list_spaces	Discover the spaces you can access	Read
get_child_pages	Browse the pages nested under a page	Read
add_comment	Add a comment or reply to a page	Action
append_to_page	Append a paragraph to the end of a page	Action
create_page	Create a new page from Markdown content	Action
update_page	Edit a page: append / replace a section / replace body	Action
add_labels	Tag a page with labels	Action

Safety by design: write tools support a preview (dry-run) mode; update_page's replace_section is idempotent; CONFLUENCE_READONLY=true disables all writes; there is no delete tool.

Search scopes: search_pages / search_comments use Confluence's CQL search, which requires the classic search:confluence scope. Every other tool uses the Confluence v2 API (granular scopes). See Connect to Copilot Studio for the full scope list.

---

Architecture

┌────────────────────┐   Bearer   ┌─────────────────────┐   REST    ┌────────────────────┐
│  Agent (Copilot    │   token    │  Confluence MCP      │  (OAuth)  │  Atlassian /       │
│  Studio / VS Code) │ ─────────► │  Server (container)  │ ────────► │  Confluence Cloud  │
└────────────────────┘    MCP     └─────────────────────┘ ◄──────── └────────────────────┘

The agent obtains an OAuth token from Atlassian and includes it as Authorization: Bearer <token> on every MCP request. The server forwards it to the Confluence Cloud REST API via https://api.atlassian.com/ex/confluence/{cloudId}/.... Reads and writes use the Confluence v2 API (/wiki/api/v2); full-text search uses the v1 CQL search endpoint (/wiki/rest/api/search), which has no v2 equivalent. It never stores credentials or acquires tokens itself.

---

Quick start (local, token mode)

The fastest way to try it — run against your own Confluence with an API token.

git clone <your-repo-url>
cd confluence-mcp-server
python -m venv .venv
# Windows: .\.venv\Scripts\Activate.ps1   |   macOS/Linux: source .venv/bin/activate
pip install -r requirements.txt

cp .env.example .env
# In .env set:
#   CONFLUENCE_AUTH_MODE=token
#   CONFLUENCE_BASE_URL=https://your-site.atlassian.net/wiki
#   CONFLUENCE_EMAIL=you@example.com
#   CONFLUENCE_API_TOKEN=...     (https://id.atlassian.com/manage-profile/security/api-tokens)

python -m confluence_mcp

The server starts on http://localhost:8000:

• Health: GET / (and /health)
• MCP endpoint: POST /mcp (streamable HTTP)

Connect to Copilot Studio (OAuth 2.0 — recommended)

Microsoft Power Platform / Copilot Studio drops extra query parameters from the OAuth authorization URL, but Atlassian requires audience=api.atlassian.com. This server ships a small /oauth/authorize proxy that re-adds it — point Copilot Studio's Authorization URL at that proxy (below).

1. Register an Atlassian OAuth 2.0 app at https://developer.atlassian.com/console/myapps/:

• Under Permissions → Confluence API → Configure → Edit Scopes, enable all of the scopes below. They live in two different sections of the console — you must add from both. Atlassian lets one app hold classic + granular scopes together, but every requested scope must be enabled here, or consent fails with "Something went wrong — information for the owner":

  Scope	Section	Enables
  read:space:confluence	Granular	list spaces
  read:page:confluence	Granular	read pages, children, title lookup
  write:page:confluence	Granular	create / update pages
  read:comment:confluence	Granular	read comments
  write:comment:confluence	Granular	add comments
  read:attachment:confluence	Granular	attachments / images
  read:label:confluence	Granular	read labels
  write:label:confluence	Granular	add labels
  search:confluence	Classic	full-text CQL search

• Under Authorization → OAuth 2.0 (3LO), set the Callback URL your agent host uses. For Copilot Studio / Power Platform custom connectors this is https://global.consent.azure-apim.net/redirect (the connector also shows a generated Redirect URL on save — register whichever your connection actually uses).

• Note the Client ID and Client Secret.

2. In Copilot Studio → your agent → Tools → Add a tool → New tool → Model Context Protocol, authentication OAuth 2.0:

Field	Value
Server URL	https://<your-host>/mcp
Authorization URL	https://<your-host>/oauth/authorize ← the proxy, no query string
Token URL	https://auth.atlassian.com/oauth/token
Refresh URL	https://auth.atlassian.com/oauth/token
Client ID / Secret	from your Atlassian app
Scopes (space-separated)	read:space:confluence read:page:confluence write:page:confluence read:comment:confluence write:comment:confluence read:attachment:confluence read:label:confluence write:label:confluence search:confluence offline_access

3. Save the connector, copy its generated Redirect URL, and confirm it is listed in your Atlassian app's Callback URLs. Create the connection and complete the consent prompt.

Changing scopes later? Delete and recreate the connection — an existing connection keeps its original token and scopes.

The agent now sends its Bearer token to the server on every call, all 16 tools appear, and each user acts as their own Confluence identity.

OAuth authorize proxy

Atlassian's OAuth 2.0 (3LO) requires audience=api.atlassian.com on the /authorize request. Some clients — notably Microsoft Power Platform / Copilot Studio — do not forward extra query parameters placed on the authorization URL, so Atlassian rejects the request (invalid_request — incorrect request parameters).

The server exposes GET /oauth/authorize to fix this: it copies the incoming query parameters, injects audience=api.atlassian.com (and prompt=consent), and 302-redirects to https://auth.atlassian.com/authorize. Point your client's Authorization URL at https://<your-host>/oauth/authorize (no query string needed).

Overridable via env: ATLASSIAN_AUTHORIZE_URL, ATLASSIAN_AUDIENCE.

Connect to VS Code (GitHub Copilot)

Add an MCP server entry (e.g. in .vscode/mcp.json):

{
  "servers": {
    "confluence": { "type": "http", "url": "http://localhost:8000/mcp" }
  }
}

For a remote OAuth-protected deployment, point url at https://<your-host>/mcp; VS Code will run the OAuth flow. Then use Copilot Chat in Agent mode.

Local development

Use token mode to run and test without OAuth:

# .env
CONFLUENCE_AUTH_MODE=token
CONFLUENCE_BASE_URL=https://your-site.atlassian.net/wiki
CONFLUENCE_EMAIL=you@example.com
CONFLUENCE_API_TOKEN=...

python -m confluence_mcp        # run the server
pytest                          # run unit tests
ruff check .                    # lint

In token mode the server uses one shared identity (your token) for all callers — intended only for local development or single-user self-hosting.

Configuration

Variable	Required	Description
CONFLUENCE_AUTH_MODE	no	oauth (default) or token.
HOST / PORT	no	Bind address / port (default 0.0.0.0:8000).
CONFLUENCE_READONLY	no	true disables all write tools.
CONFLUENCE_DEFAULT_SPACE	no	Default space key for create_page.
CONFLUENCE_SITE_URL	no	(oauth) Pin to one site if the token can access several.
MCP_ALLOWED_HOSTS	no	Comma-separated Host values to allow (turns on MCP DNS-rebinding protection). Default: disabled — appropriate behind an authenticating TLS gateway/ingress.
ATLASSIAN_AUDIENCE	no	Audience injected by the /oauth/authorize proxy (default api.atlassian.com).
ATLASSIAN_AUTHORIZE_URL	no	Upstream authorize URL for the proxy (default https://auth.atlassian.com/authorize).
CONFLUENCE_BASE_URL	token mode	Your Confluence base URL, ending in /wiki.
CONFLUENCE_EMAIL	token mode	Atlassian account email.
CONFLUENCE_API_TOKEN	token mode	Atlassian API token.

See .env.example.

Deploy

Docker

docker build -t confluence-mcp-server .
docker run -p 8000:8000 --env-file .env confluence-mcp-server

Azure Container Apps

az containerapp up \
  --name confluence-mcp \
  --resource-group my-rg \
  --location eastus \
  --ingress external --target-port 8000 \
  --source .
# then set app settings (env vars):
az containerapp update --name confluence-mcp --resource-group my-rg \
  --set-env-vars CONFLUENCE_AUTH_MODE=oauth

Your MCP endpoint is https://<app-fqdn>/mcp. The image also runs on any container host (App Service for Containers, AWS ECS, Cloud Run, etc.).

Security model

• oauth mode (default): no credentials are stored on the server; the agent supplies a Bearer token per request and every caller acts as their own Confluence user, respecting their existing permissions.
• token mode: a single static identity — keep the token secret; use only for local dev or single-user self-hosting.
• CONFLUENCE_READONLY=true disables all write tools. There is no delete tool.
• Write tools support preview (dry-run); update_page's replace_section is idempotent.

License

MIT

Contributing

See CONTRIBUTING.md.