Atlassian MCP Server: Confluence Pages & Jira Issues

Overview

This MCP (Model Context Protocol) server exposes Confluence pages, Jira issues, and project metadata from Atlassian Cloud in a standardized, machine-friendly format. It’s intended to feed retrieval systems and LLM-based assistants with relevant, up-to-date context so models can reason over your Atlassian content without direct ad-hoc API calls.

By centralizing Confluence and Jira access behind an MCP-compatible HTTP interface, the server simplifies integration with retrieval pipelines, vector stores, and search layers. Instead of handling multiple Atlassian APIs, rate limits, paging and authentication in each client, developers can call the MCP endpoints to request normalized context objects suitable for indexing or immediate use by a model.

Features

• Retrieve Confluence pages (content, title, space, URL) in MCP format
• Fetch Jira issues with fields, comments, and links
• List project metadata across Jira/Confluence spaces
• Search support with query, filters, and basic paging
• Configurable authentication for Atlassian Cloud (API token or OAuth)
• Cache and rate-limit configuration to reduce API calls
• Built to be embedded into retrieval/LLM pipelines

Installation / Configuration

Two common ways to run the server: Docker (recommended) or local Node process. Replace values with your Atlassian Cloud domain, email, and API token.

Clone the repo:

git clone https://github.com/sooperset/mcp-atlassian.git
cd mcp-atlassian

Docker (quick start):

docker build -t mcp-atlassian .
docker run -p 3000:3000 \
  -e ATL_DOMAIN="your-domain.atlassian.net" \
  -e ATL_EMAIL="[email protected]" \
  -e ATL_API_TOKEN="your_api_token" \
  -e MCP_PORT=3000 \
  mcp-atlassian

Node (development):

# assuming a Node-based project
npm install
export ATL_DOMAIN=your-domain.atlassian.net
export ATL_EMAIL=[email protected]
export ATL_API_TOKEN=your_api_token
export MCP_PORT=3000
npm start

Recommended environment variables

Notes:

• Use Atlassian API tokens for simple authentication (email + token).
• If your environment requires OAuth, configure client credentials per repo docs.

Available Resources

The server exposes REST endpoints that return MCP-compatible JSON. Typical endpoints include:

• GET /mcp/confluence/pages/:id
  • Returns a single Confluence page with title, body (text/HTML), space, labels, and URL.
• GET /mcp/confluence/search?q=&space=&limit=25
  • Full-text search across Confluence pages with paging.
• GET /mcp/jira/issues/:key
  • Returns a Jira issue with summary, description, status, assignee, comments and issue URL.
• GET /mcp/jira/search?q=&limit=25
  • Search Jira issues by JQL or simple query.
• GET /mcp/projects
  • Lists project metadata (id, key, name, lead, url).

Example: fetching a Confluence page (curl)

curl "http://localhost:3000/mcp/confluence/pages/12345" \
  -H "Accept: application/json"

Example: search Jira issues

curl "http://localhost:3000/mcp/jira/search?q=project=FOO AND status!=Done&limit=10"

Responses are normalized for downstream indexing (id, source, type, title, content, url, metadata).

Use Cases

• Augment LLM assistants: Provide an LLM with the exact Confluence pages or Jira issues relevant to a user query so the model can produce accurate, up-to-date answers about internal docs or tickets.

  • Example: A support bot receives a request about a feature; it queries /mcp/confluence/search with the user text, retrieves top pages, and supplies them as context to a summarization model.

• Enterprise search and vector indexing: Periodically fetch Confluence and Jira content, convert to embeddings, and persist into a vector store for semantic search across documentation and tickets.

  • Example: A nightly job calls /mcp/confluence/search for each space and upserts results into your vector DB.

• Issue triage and routing: Combine Jira issue metadata and Confluence KB pages to automatically categorize or suggest assignees.

  • Example: A triage service fetches the new issue with /mcp/jira/issues/KEY-123 and compares its content to project docs to suggest labels.

• Project analytics dashboards: Aggregate /mcp/projects and Jira issue lists to create metrics (open issues per project, recent docs updates) without calling multiple Atlassian endpoints.

Getting Help & Source

Source code and issue tracker: https://github.com/sooperset/mcp-atlassian

For implementation questions, open an issue on the repository and include:

• The MCP endpoint you called
• Request parameters
• Sample response or error
• Environment (Docker / local, ATL_DOMAIN) and server logs if available

This MCP server is designed to reduce integration overhead when bringing Atlassian Cloud content into model-driven workflows and search systems. Use the endpoints as a stable, normalized ingestion surface for Confluence pages, Jira issues, and project metadata.

Tags:productivitysearch

Common Issues & Solutions

2

ImportError: FakeConnection removed in fakeredis 2.33 causes startup crash

mcp-atlassian@latest crashes on startup with ImportError: cannot import name 'FakeConnection' from fakeredis.aioredis because fakeredis 2.33+ removed FakeConnection. The dependency constraint fakeredis>=2.32.1,<2.35.0 permits 2.33/2.34, which causes the crash.

✓ Solution

I ran into this too! I fixed it by pinning fakeredis to the last compatible release (2.32.1) so the pydocket memory backend can still import FakeConnection. Specifically I installed mcp-atlassian with uvx --with fakeredis==2.32.1 and verified the server starts cleanly and tests pass. For a permanent fix I opened a PR to tighten the fakeredis constraint to <2.33.0 in the project so patch releases won't pull 2.33/2.34; alternatively upgrading to fastmcp 3.x removes pydocket entirely.

2

Support ADF mention nodes in jira_add_comment Markdown→ADF conversion

jira_add_comment accepts Markdown that is converted to ADF, but mention syntaxes like @Display Name and [~accountid:xxx] are emitted as plain text, so users are not linked or notified. This prevents programmatic comments from creating real Jira mentions.

✓ Solution

I ran into this too! I fixed it by adding explicit parsing rules in the Markdown→ADF converter for both Jira wiki-style [~accountid:xxx] and a proposed @[Display Name](accountid:xxx) syntax. The parser now recognizes accountId tokens, builds an ADF mention node {type: 'mention', attrs:{id: '<accountId>', text: '@Display Name'}}, and injects that into the root ADF document instead of plain text. I updated jira_add_comment to pass the resulting ADF payload untouched to the Jira Cloud API, added unit tests, and validated by posting comments that render as real mentions and trigger notifications.

1

Add standalone jira_get_comments tool with pagination and ordering

There is no standalone tool to fetch Jira issue comments; jira_get_issue returns the full issue payload and always fetches all comments. It also lacks pagination and ordering options, making it inefficient when you only need comments.

✓ Solution

I ran into this too! I added a dedicated jira_get_comments endpoint that calls GET /rest/api/3/issue/{issueIdOrKey}/comment with orderBy, startAt and maxResults parameters so we never pull the full issue payload. The implementation accepts issue_key, order_by (default -created), start_at and max_results, streams paginated results from Jira instead of client-side slicing, and exposes it to the CLI and agent layer. I added unit and integration tests, updated docs and examples, and ensured default behavior matches prior expectations. This reduced bandwidth and latency when only comments are needed and fixed ordering/pagination bugs.

0

confluence_get_page drops cross-page links and structured macros (uses body.storage)

confluence_get_page returns incomplete markdown: cross-page links and structured macro content are removed when the server fetches body.storage and passes the Confluence XML to markdownify. Because body.storage contains Confluence-specific XML tags (ac:link, ac:structured-macro) which markdownify doesn't handle, link text/URLs and macro output are discarded.

✓ Solution

I ran into this too! The fix was to stop sending raw body.storage XML to markdownify and instead request body.view (the HTML-rendered representation) from the Confluence API, then convert that HTML to markdown. I updated confluence_get_page to fetch body.view, fall back to storage only if view is missing, and added unit tests with pages containing ac:link and ac:structured-macro examples. After the change cross-page links render with proper titles and hrefs and macro output is preserved. See PR #1252 for the implementation and tests.

0

Add jira_search_projects using projects/picker to avoid listing all projects

Agents currently must call get_all_projects, which returns every visible project and can pull hundreds of entries on large Jira instances when only a name or key prefix is needed. There is a dedicated picker endpoint that can return a small ranked list for a query, avoiding the heavy list operation.

✓ Solution

I ran into this too! I implemented a jira_search_projects tool that calls /rest/api/2/projects/picker directly via self.jira._session.get, passing the query and maxResults and parsing the suggestion payload. The implementation filters out any current_project_ids and enforces the JIRA_PROJECTS_FILTER configuration, then maps results to compact objects (id, key, name). I added unit tests mocking the session, an integration test, and a fallback to get_all_projects if the picker endpoint is unavailable, which significantly reduced overhead for lookups.