Atlassian Data Center MCP

Note: This is a community-maintained project and is not affiliated with, endorsed by, or supported by Atlassian. Use at your own discretion.

This project provides a Model Context Protocol (MCP) integration for Atlassian Data Center products, including Jira, Confluence, and Bitbucket.

Quick Setup

Each package ships an interactive setup subcommand that stores your credentials in the most secure place available on your OS. Run it once per product:

npx jira-datacenter-mcp setup
npx confluence-datacenter-mcp setup
npx bitbucket-datacenter-mcp setup

The setup CLI prompts for host, API base path, default page size, and API token. The token can be left blank for instances that allow anonymous access — the MCP server then makes unauthenticated requests. Before saving, it validates obvious input mistakes and, if a token was entered, performs a timed authenticated request to the selected Atlassian product, so a bad host, base path, or token is caught during setup.

CLI flags and non-interactive mode

Setup accepts flags so you can prefill values or skip prompts entirely (useful for scripted bootstrap, CI, or remote sessions). Run npx <product>-datacenter-mcp setup --help for the full list.

In interactive mode, any flag you pass prefills its prompt (so e.g. --host skips the host prompt but still asks for the rest). In --non-interactive mode, setup resolves anything missing from existing configuration (process env, ~/.atlassian-dc-mcp/<product>.env, or macOS Keychain) and exits non-zero only if a host (or full-URL --api-base-path) cannot be found. The token is optional — omit it (and don't keep an existing one) to configure anonymous access. An existing token is reused when --token is omitted; an existing password is reused the same way when --password is omitted. Basic auth (--username/--password) takes precedence over the token when both are configured.

Multiple instances per product (profiles)

By default, setup reads and writes one unsuffixed home file / Keychain entry per product. To manage more than one instance of the same product (e.g. two separate Jira Data Center sites), give each one a distinct --profile name at setup time, then set ATLASSIAN_DC_MCP_PROFILE to the same name when launching the server so it reads that profile back:

npx jira-datacenter-mcp setup --profile work --host jira-work.example.com --token "$WORK_TOKEN"
npx jira-datacenter-mcp setup --profile personal --host jira-personal.example.com --token "$PERSONAL_TOKEN"

{
  "mcpServers": {
    "atlassian-jira-work": {
      "command": "npx",
      "args": ["-y", "jira-datacenter-mcp"],
      "env": { "ATLASSIAN_DC_MCP_PROFILE": "work" }
    },
    "atlassian-jira-personal": {
      "command": "npx",
      "args": ["-y", "jira-datacenter-mcp"],
      "env": { "ATLASSIAN_DC_MCP_PROFILE": "personal" }
    }
  }
}

A profile only changes which home file (~/.atlassian-dc-mcp/<product>.<profile>.env) and Keychain account (<product>-<profile>-token / <product>-<profile>-password) are used — it has no effect on process.env or ATLASSIAN_DC_MCP_CONFIG_FILE, which already let you point separate processes at fully separate configuration and take priority over both regardless of profile.

# Scripted, no prompts, write everything from flags
npx jira-datacenter-mcp setup --non-interactive \
  --host jira.example.com \
  --token "$JIRA_TOKEN"

# Re-validate the existing token without re-entering it
npx jira-datacenter-mcp setup --non-interactive --host jira.example.com

Credential validation behaves differently between modes: interactive mode offers retry/save-anyway prompts on failure, while --non-interactive exits with code 1 on the first validation failure so it can be used as a CI gate.

Token storage:

• macOS — written to the login Keychain via /usr/bin/security (service atlassian-dc-mcp, account <product>-token).
• Linux — written to ~/.atlassian-dc-mcp/<product>.env with POSIX mode 0600 (read/write for your user only; other local user accounts cannot read it).
• Windows — written to %USERPROFILE%\.atlassian-dc-mcp\<product>.env. Node passes the mode bits but Windows ignores them, so the file inherits the ACL of your user profile directory — typically readable only by your user, SYSTEM, and Administrators.

Non-secret fields (host, API base path, default page size) are always written to the home file — ~/.atlassian-dc-mcp/<product>.env on macOS/Linux, %USERPROFILE%\.atlassian-dc-mcp\<product>.env on Windows. After a successful Keychain write, the token line is cleared from the home file so there is never a second copy in a less-secure place.

Once setup has run, the MCP servers can boot with no environment variables at all:

{
  "mcpServers": {
    "atlassian-jira-dc": { "command": "npx", "args": ["-y", "jira-datacenter-mcp"] },
    "atlassian-confluence-dc": { "command": "npx", "args": ["-y", "confluence-datacenter-mcp"] },
    "atlassian-bitbucket-dc": { "command": "npx", "args": ["-y", "bitbucket-datacenter-mcp"] }
  }
}

You can still pass credentials via environment variables or ATLASSIAN_DC_MCP_CONFIG_FILE as shown in the sections below — they take precedence over values saved by setup.

Configuration Sources & Precedence

At startup, each MCP server resolves each config key by walking sources in this order and taking the first non-empty value:

Notes:

• Process env wins over everything, so you can always override a stored credential for one session.
• ATLASSIAN_DC_MCP_CONFIG_FILE must be an absolute path; if set and missing, the server fails fast.
• Keychain reads are cached at init (one execFileSync per product-secret), so tool calls never shell out.
• If a higher-priority source shadows the value setup is about to save, setup prints a warning naming the env var so you can unset it.
• Atlassian API requests time out after 30 seconds by default. Set ATLASSIAN_DC_MCP_REQUEST_TIMEOUT_MS to a positive millisecond value to override it.
• Transient failures (HTTP 429 and 5xx) are retried automatically with exponential backoff and jitter (up to 3 retries) before a tool call reports an error. 4xx client errors (bad input, auth, not found, ...) are never retried.
• datacenter-mcp-core exports a paginateAll helper for auto-paginating naturally small, bounded startAt-paged endpoints (e.g. a project's versions, a page's labels) internally in a service method, so callers get one fully-assembled list instead of hand-rolling a startAt loop. It's not used for open-ended search endpoints (JQL/CQL, repository listings), which stay single-page and agent-driven so a broad query can't flood the conversation with an unbounded amount of data.
• Each product also accepts *_USERNAME/*_PASSWORD for Basic auth, as an alternative to *_API_TOKEN (useful for older instances without personal access tokens). If both are set, Basic auth takes precedence over the Bearer token.

Transport

By default, every MCP server speaks stdio — what Claude Desktop and other local MCP hosts expect. Setting ATLASSIAN_DC_MCP_HTTP_PORT to a positive integer instead starts the MCP Streamable HTTP transport (the current spec's recommendation for remote/multi-client access, superseding the legacy SSE transport) on that port; the two transports are mutually exclusive per process — set the env var only for a standalone, network-reachable instance, not for a Claude Desktop-launched one:

ATLASSIAN_DC_MCP_HTTP_PORT=3000 npx jira-datacenter-mcp

The transport is stateful: it demultiplexes many concurrent client sessions by the Mcp-Session-Id header over one long-lived process, so exposing it beyond localhost needs your own reverse proxy / TLS termination and network access control — the transport itself does not add authentication on top of the Atlassian credentials already configured for the server.

Logging

The stdio transport reserves stdout exclusively for JSON-RPC protocol messages, so all logging — at any level, on any transport — goes to stderr as one JSON object per line ({"timestamp", "level", "message", ...fields}), safe to capture separately from the protocol stream. Levels are debug < info < warn < error; the default is info. Set ATLASSIAN_DC_MCP_LOG_LEVEL to change it:

ATLASSIAN_DC_MCP_LOG_LEVEL=debug npx jira-datacenter-mcp

Claude Desktop Configuration

Official Anthropic quick start guide

To use these MCP connectors with Claude Desktop, add the following to your Claude Desktop configuration.

Set *_HOST variables only to domain + port without protocol (e.g., your-instance.atlassian.net). The https protocol is assumed.

Alternatively, you can use *_API_BASE_PATH variables instead of *_HOST to specify the complete API base URL including protocol (e.g., https://your-instance.atlassian.net/rest). Note that the /api/latest/ part is static and added automatically in the code, so you don't need to include it in the *_API_BASE_PATH values.

You can leave only the services you need in the configuration.

macOS:

~/Library/Application Support/Claude/claude_desktop_config.json

Windows:

%APPDATA%\Claude\claude_desktop_config.json

{
  "mcpServers": {
    "atlassian-jira-dc": {
      "command": "npx",
      "args": ["-y", "jira-datacenter-mcp"],
      "env": {
        "JIRA_HOST": "your-jira-host",
        "JIRA_API_TOKEN": "your-token"
      }
    },
    "atlassian-confluence-dc": {
      "command": "npx",
      "args": ["-y", "confluence-datacenter-mcp"],
      "env": {
        "CONFLUENCE_HOST": "your-confluence-host",
        "CONFLUENCE_API_TOKEN": "your-token"
      }
    },
    "atlassian-bitbucket-dc": {
      "command": "npx",
      "args": ["-y", "bitbucket-datacenter-mcp"],
      "env": {
        "BITBUCKET_HOST": "your-bitbucket-host",
        "BITBUCKET_API_TOKEN": "your-token"
      }
    }
  }
}

You can also use the alternative API base path configuration:

{
  "mcpServers": {
    "atlassian-jira-dc": {
      "command": "npx",
      "args": ["-y", "jira-datacenter-mcp"],
      "env": {
        "JIRA_API_BASE_PATH": "https://your-jira-host/rest",
        "JIRA_API_TOKEN": "your-token"
      }
    },
    "atlassian-confluence-dc": {
      "command": "npx",
      "args": ["-y", "confluence-datacenter-mcp"],
      "env": {
        "CONFLUENCE_API_BASE_PATH": "https://your-confluence-host/rest",
        "CONFLUENCE_API_TOKEN": "your-token"
      }
    },
    "atlassian-bitbucket-dc": {
      "command": "npx",
      "args": ["-y", "bitbucket-datacenter-mcp"],
      "env": {
        "BITBUCKET_API_BASE_PATH": "https://your-bitbucket-host/rest",
        "BITBUCKET_API_TOKEN": "your-token"
      }
    }
  }
}

Shared External Config File

If you want multiple MCP hosts or tools on one machine to reuse the same Atlassian credentials, put the existing JIRA_*, CONFLUENCE_*, and BITBUCKET_* variables into one dotenv-style file and point each MCP server at it with ATLASSIAN_DC_MCP_CONFIG_FILE.

The path must be absolute. Direct environment variables still override values from the shared file.

Example shared file:

JIRA_HOST=your-jira-host
JIRA_API_TOKEN=your-jira-token
JIRA_DEFAULT_PAGE_SIZE=50

CONFLUENCE_HOST=your-confluence-host
CONFLUENCE_API_TOKEN=your-confluence-token

BITBUCKET_HOST=your-bitbucket-host
BITBUCKET_API_TOKEN=your-bitbucket-token
BITBUCKET_DEFAULT_PAGE_SIZE=50

Claude Desktop example using one shared file:

{
  "mcpServers": {
    "atlassian-jira-dc": {
      "command": "npx",
      "args": ["-y", "jira-datacenter-mcp"],
      "env": {
        "ATLASSIAN_DC_MCP_CONFIG_FILE": "/Users/your-user/.config/atlassian-dc-mcp.env"
      }
    },
    "atlassian-confluence-dc": {
      "command": "npx",
      "args": ["-y", "confluence-datacenter-mcp"],
      "env": {
        "ATLASSIAN_DC_MCP_CONFIG_FILE": "/Users/your-user/.config/atlassian-dc-mcp.env"
      }
    },
    "atlassian-bitbucket-dc": {
      "command": "npx",
      "args": ["-y", "bitbucket-datacenter-mcp"],
      "env": {
        "ATLASSIAN_DC_MCP_CONFIG_FILE": "/Users/your-user/.config/atlassian-dc-mcp.env"
      }
    }
  }
}

Windows example path:

{
  "mcpServers": {
    "atlassian-jira-dc": {
      "command": "npx",
      "args": ["-y", "jira-datacenter-mcp"],
      "env": {
        "ATLASSIAN_DC_MCP_CONFIG_FILE": "C:\\\\Users\\\\your-user\\\\AppData\\\\Roaming\\\\atlassian-dc-mcp.env"
      }
    }
  }
}

Claude Code CLI Configuration

To use these MCP connectors with Claude Code, add MCP servers using the claude mcp add command.

You can add servers at the project scope (stored in .mcp.json) or user scope (-s user). Adjust the scope and included services to your needs.

# Jira
claude mcp add atlassian-jira-dc \
  -e JIRA_HOST=your-jira-host \
  -e JIRA_API_TOKEN=your-token \
  -- npx -y jira-datacenter-mcp

# Confluence
claude mcp add atlassian-confluence-dc \
  -e CONFLUENCE_HOST=your-confluence-host \
  -e CONFLUENCE_API_TOKEN=your-token \
  -- npx -y confluence-datacenter-mcp

# Bitbucket
claude mcp add atlassian-bitbucket-dc \
  -e BITBUCKET_HOST=your-bitbucket-host \
  -e BITBUCKET_API_TOKEN=your-token \
  -- npx -y bitbucket-datacenter-mcp

You can also use *_API_BASE_PATH instead of *_HOST (same as the Claude Desktop examples above):

claude mcp add atlassian-jira-dc \
  -e JIRA_API_BASE_PATH=https://your-jira-host/rest \
  -e JIRA_API_TOKEN=your-token \
  -- npx -y jira-datacenter-mcp

To add servers at user scope (available across all projects):

claude mcp add -s user atlassian-jira-dc \
  -e JIRA_HOST=your-jira-host \
  -e JIRA_API_TOKEN=your-token \
  -- npx -y jira-datacenter-mcp

To use the shared config file instead of passing credentials inline:

claude mcp add atlassian-jira-dc \
  -e ATLASSIAN_DC_MCP_CONFIG_FILE=/Users/your-user/.config/atlassian-dc-mcp.env \
  -- npx -y jira-datacenter-mcp

Windows PowerShell example:

claude mcp add atlassian-jira-dc `
  -e ATLASSIAN_DC_MCP_CONFIG_FILE=C:\Users\your-user\AppData\Roaming\atlassian-dc-mcp.env `
  -- npx -y jira-datacenter-mcp

Generating API Tokens

For Data Center installations, you'll need to generate Personal Access Tokens (PAT) for each service:

Jira Data Center

1. Log in to your Jira instance
2. Go to Profile > Personal Access Tokens
3. Click "Create token"
4. Give it a meaningful name and set appropriate permissions
5. Copy the generated token immediately (it won't be shown again)

Confluence Data Center

1. Log in to your Confluence instance
2. Go to Settings > Personal Access Tokens
3. Click "Create token"
4. Name your token and set required permissions
5. Save and copy the token (only shown once)

Bitbucket Data Center

1. Log in to Bitbucket
2. Go to Manage Account > HTTP access tokens
3. Click "Create token"
4. Set a name and permissions
5. Generate and copy the token immediately

Store these tokens securely and use them in your Claude Desktop configuration as shown above.

Overview

The Atlassian DC MCP allows AI assistants to interact with Atlassian products through a standardized interface. It provides tools for:

• Jira: Search, view, and create issues
• Confluence: Access and manage content
• Bitbucket: Interact with repositories and code

Prerequisites

• Node.js 26 or higher
• pnpm (pinned via the packageManager field, currently 11.9.0) — install however's convenient: the standalone installer, npm install -g pnpm, or Corepack if you already have it. CI uses pnpm/action-setup, independent of Corepack.
• Atlassian Data Center instance or Cloud instance
• API tokens for the Atlassian products you want to use (optional if the instance allows anonymous access)

Installation

Clone the repository:

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

Development

This project is structured as a pnpm monorepo using workspaces (see pnpm-workspace.yaml). The workspaces are organized in the packages/ directory, with separate packages for each Atlassian product integration.

Installing Dependencies

To install all dependencies for all packages in the monorepo:

pnpm install

This will install:

• Root-level dependencies defined in the root package.json
• All dependencies for each package in the workspaces

To install a dependency for a specific package:

pnpm add <package-name> --filter jira-datacenter-mcp

To install a dependency at the root level:

pnpm add <package-name> -w

Building the Project

To build all packages:

pnpm build

To build a specific package:

pnpm --filter jira-datacenter-mcp build

Running in Development Mode

To run a specific package in development mode:

pnpm dev:jira     # For Jira
pnpm dev:confluence  # For Confluence
pnpm dev:bitbucket   # For Bitbucket

Testing

pnpm test                                    # unit tests, all packages (mocked API client — no network)
pnpm --filter jira-datacenter-mcp test       # unit tests, one package
pnpm lint                                    # ESLint across the whole repo

Every existing test mocks the generated API client, so none of them can catch a real auth/network/API-shape regression against an actual Data Center instance. packages/jira/src/__tests__/live/jira-service.live.test.ts is a reference template for that: an opt-in, read-only smoke test that skips itself entirely (not a failure) when unconfigured, so pnpm test stays green with zero setup. To run it against a real instance:

cp packages/jira/.env.live.example packages/jira/.env.live
# edit packages/jira/.env.live with a real host + token (or username/password)
pnpm --filter jira-datacenter-mcp test -- jira-service.live

.env.live is gitignored — never commit real credentials.

Releasing

This project uses Changesets for versioning and publishing (not lerna); all 4 packages are kept in lockstep via a fixed group. Any PR that changes package behavior should include a changeset:

pnpm changeset

Pick the affected packages and bump type, write a short summary, and commit the generated .changeset/*.md file alongside your code change. Merging to master opens/updates a "Version Packages" pull request; merging that PR is what actually triggers the npm publish and MCP Registry publish.

Configuration

For production use, prefer the Quick Setup CLI above — it writes to the macOS Keychain (for tokens) and the home file for non-secret fields (~/.atlassian-dc-mcp/<product>.env on macOS/Linux, %USERPROFILE%\.atlassian-dc-mcp\<product>.env on Windows) automatically.

For local development, create a .env file in the root directory, or a shared dotenv-style file anywhere on disk and point ATLASSIAN_DC_MCP_CONFIG_FILE to it, with the following variables:

# Jira configuration - choose one of these options:
JIRA_HOST=your-instance.atlassian.net
# OR
JIRA_API_BASE_PATH=https://your-instance.atlassian.net/rest
# Note: part /api/2/search/ is added automatically, do not include it
JIRA_API_TOKEN=your-api-token

# Confluence configuration - choose one of these options:
CONFLUENCE_HOST=your-instance.atlassian.net
# OR
CONFLUENCE_API_BASE_PATH=https://your-instance.atlassian.net/confluence
# Note: part /rest/api is added automatically, do not include it
CONFLUENCE_API_TOKEN=your-api-token

# Bitbucket configuration - choose one of these options:
BITBUCKET_HOST=your-instance.atlassian.net
# OR
BITBUCKET_API_BASE_PATH=https://your-instance.atlassian.net/rest
# Note: part /api/latest/ is added automatically, do not include it
BITBUCKET_API_TOKEN=your-api-token

Only a host (or full-URL API base path) is required. *_API_TOKEN is optional — omit it to connect anonymously, for instances that allow unauthenticated read access. Without a token, no Authorization header is sent at all.

Resolution order for each key is process.env → ATLASSIAN_DC_MCP_CONFIG_FILE (or ./.env) → home file (~/.atlassian-dc-mcp/<product>.env on macOS/Linux, %USERPROFILE%\.atlassian-dc-mcp\<product>.env on Windows) → macOS Keychain. See Configuration Sources & Precedence above.

License

MIT