MCP Atlassian Node Server

Production-ready MCP (Model Context Protocol) server for Atlassian Jira and Confluence built with Node.js + TypeScript.

Features

• Node 20+ TypeScript ESM server.

• MCP tools for generic Jira/Confluence proxy calls and high-level wrappers.

• Auth modes:

  • Service-specific Basic auth via JIRA_EMAIL + JIRA_API_TOKEN and CONFLUENCE_EMAIL + CONFLUENCE_API_TOKEN.

  • Service-specific Bearer auth via JIRA_BEARER_TOKEN and CONFLUENCE_BEARER_TOKEN.

  • Global fallback auth via ATLASSIAN_* when service-specific values are not provided.

• Config validation with clear startup errors.

• HTTP layer powered by undici:

  • retries with exponential backoff

  • respects Retry-After

  • request/response logging with token redaction

  • configurable timeout (30s)

  • max response size limit (10 MB)

• Security controls:

  • base URL allowlist derived from config (SSRF prevention)

  • path prefix validation for Jira/Confluence APIs

  • optional TLS verification bypass for self-signed corporate cert chains (SSL_VERIFY=false)

• Confluence normalization helpers:

  • plain text extraction from storage HTML

  • normalized document object with metadata and attachments

Requirements

• Node.js >=20

• npm

Install

npm i

Configuration

Copy .env.example and set values:

ATLASSIAN_SITE=https://company.atlassian.net
JIRA_BASE_URL=https://jira.company.internal
JIRA_API_VERSION=2
CONFLUENCE_BASE_URL=https://wiki.company.internal
CONFLUENCE_API_PREFIX=/rest/api

# Optional global fallback auth
ATLASSIAN_EMAIL=you@company.com
ATLASSIAN_API_TOKEN=global_fallback_token
ATLASSIAN_BEARER_TOKEN=

# Jira auth
JIRA_EMAIL=you@company.com
JIRA_API_TOKEN=jira_api_token
JIRA_BEARER_TOKEN=

# Confluence auth
CONFLUENCE_EMAIL=you@company.com
CONFLUENCE_API_TOKEN=confluence_api_token
CONFLUENCE_BEARER_TOKEN=

SSL_VERIFY=true
USER_AGENT=jira-mcp

Environment variables

• ATLASSIAN_SITE (required): base site URL, e.g. https://company.atlassian.net

• JIRA_BASE_URL (optional): defaults to ATLASSIAN_SITE

• JIRA_API_VERSION (optional, 2/3, default 2): Jira REST API version used by Jira tools and relative jira_request paths

• CONFLUENCE_BASE_URL (optional): defaults to ATLASSIAN_SITE

• CONFLUENCE_API_PREFIX (optional): Confluence REST prefix.

  • Cloud default: /wiki/rest/api

  • Server/Data Center default: /rest/api

  • Custom context path example: /confluence/rest/api

• JIRA_BEARER_TOKEN (optional): Jira Bearer token, takes precedence for Jira requests

• CONFLUENCE_BEARER_TOKEN (optional): Confluence Bearer token, takes precedence for Confluence requests

• JIRA_EMAIL (optional): Jira Basic auth email

• JIRA_API_TOKEN (optional): Jira Basic auth token

• CONFLUENCE_EMAIL (optional): Confluence Basic auth email

• CONFLUENCE_API_TOKEN (optional): Confluence Basic auth token

• ATLASSIAN_BEARER_TOKEN (optional): global Bearer fallback for any service without service-specific bearer token

• ATLASSIAN_EMAIL (optional): global Basic auth email fallback

• ATLASSIAN_API_TOKEN (optional): global Basic auth token fallback

• SSL_VERIFY (optional, true/false, default true)

• USER_AGENT (optional, default jira-mcp)

Run

Development:

npm run dev

Build:

npm run build

Start built server:

npm start

Manual smoke test (direct API calls):

npm run build
npm run manual:test

MCP Tools

Generic proxy tools

• jira_request

• confluence_request

jira_request uses JIRA_API_VERSION when apiVersion is not provided.

Both return:

{
  "status": 200,
  "headers": {
    "content-type": "application/json"
  },
  "body": {}
}

Jira tools

• jira_search_issues

• jira_get_issue

• jira_get_project

• jira_list_projects

• jira_get_transitions

• jira_transition_issue

• jira_add_comment

• jira_get_users

• jira_download_attachment

jira_download_attachment:

• input: attachmentId, optional mode (base64 or file)

• output always uses { status, headers, body }; for non-2xx Jira responses it still returns this shape with error details in body

Confluence tools

• confluence_get_page

• confluence_search

• confluence_get_children

• confluence_get_page_content

• confluence_get_attachments

• confluence_download_attachment

confluence_get_page_content returns:

• original Confluence page payload

• normalized document

{
  "id": "12345",
  "title": "Page Title",
  "url": "https://company.atlassian.net/wiki/spaces/ENG/pages/12345/Page+Title",
  "spaceKey": "ENG",
  "updatedAt": "2025-01-01T12:00:00.000Z",
  "text": "Plain text extracted from storage HTML",
  "html": "<p>Original storage HTML</p>",
  "breadcrumbs": ["Parent", "Child"],
  "labels": ["runbook"],
  "attachments": [
    {
      "id": "att-1",
      "title": "diagram.png",
      "mediaType": "image/png",
      "fileSize": 10240,
      "downloadUrl": "https://company.atlassian.net/wiki/download/attachments/..."
    }
  ]
}

Authentication examples

Different servers, different tokens:

JIRA_BASE_URL=https://jira.company.internal
JIRA_API_VERSION=2
CONFLUENCE_BASE_URL=https://wiki.company.internal
CONFLUENCE_API_PREFIX=/rest/api
JIRA_BEARER_TOKEN=jira_bearer_token
CONFLUENCE_BEARER_TOKEN=confluence_bearer_token

Different Basic tokens:

JIRA_EMAIL=you@company.com
JIRA_API_TOKEN=jira_api_token
CONFLUENCE_EMAIL=you@company.com
CONFLUENCE_API_TOKEN=confluence_api_token

Global fallback for both services:

ATLASSIAN_EMAIL=you@company.com
ATLASSIAN_API_TOKEN=global_api_token
# or
ATLASSIAN_BEARER_TOKEN=global_bearer_token

Corporate proxy / self-signed cert support

To disable TLS certificate verification explicitly:

SSL_VERIFY=false

Default is secure verification (SSL_VERIFY=true).

Notes

• Tokens are never printed in logs.

• HTTP logs are emitted to stderr so MCP stdio communication remains valid on stdout.

• HTTP 3xx redirects are treated as errors (HTTP_REDIRECT) to surface auth/login redirect issues explicitly.

• If Confluence returns redirect to login.action with fourohfour.action, set CONFLUENCE_API_PREFIX for your deployment (commonly /rest/api for Server/DC).

• If official MCP SDK loading fails, a minimal JSON-RPC stdio adapter starts automatically.

How to add to cursor:

{
  "mcpServers": {
    "atlassian": {
      "command": "node",
      "args": ["/your/path/to/JIRA_MCP/dist/index.js"],
      "env": {
        "ATLASSIAN_SITE": "https://company.atlassian.net",
        "JIRA_BASE_URL": "https://jira.company.internal",
        "JIRA_API_VERSION": "2",
        "CONFLUENCE_BASE_URL": "https://wiki.company.internal",
        "CONFLUENCE_API_PREFIX": "/rest/api",
        "JIRA_BEARER_TOKEN": "jira_token",
        "CONFLUENCE_BEARER_TOKEN": "confluence_token",
        "SSL_VERIFY": "true"
      }
    }
  }
}

Publishing to npm

1. Имя пакета: @alexbuzo/jira-mcp. Проверка: npm view @alexbuzo/jira-mcp.

2. Вход в npm: npm login (или npm login --registry=https://registry.npmjs.org/).

3. Сборка перед публикацией выполняется автоматически скриптом prepublishOnly (npm run build).

4. Публикация (в package.json задано publishConfig.access: public):

   npm publish

   При необходимости явно: npm publish --access public.

5. После публикации в Cursor через npx:

   "command": "npx",
   "args": ["-y", "@alexbuzo/jira-mcp"],
   "env": { ... }

Или command: jira-mcp, если пакет установлен глобально (npm i -g @alexbuzo/jira-mcp — исполняемый файл по-прежнему называется jira-mcp).