Atlassian Dc MCP Server

Atlassian Data Center MCP

Community project — not affiliated with, endorsed by, or supported by Atlassian. Use at your own discretion.

Model Context Protocol (MCP) servers that connect Claude Desktop, Claude Code, Cursor, and any other MCP-compatible AI assistant to self-hosted Atlassian Data Center (formerly Server) instances: Jira, Confluence, and Bitbucket.

Search and manage Jira issues, read and edit Confluence pages, review Bitbucket pull requests — from your AI assistant, with credentials stored in your OS keychain instead of pasted into a client config.

Each product is a separate package — install only the ones you need.

---

Contents

• Capabilities
• Quick start
• Connecting a client — Claude Desktop · Claude Code · Cursor & others
• Authentication & tokens
• Configuration reference
• Features
• Development
• License

---

Capabilities

Each server exposes MCP tools (actions the assistant can call), resources (readable context endpoints), and prompts (ready-made workflows). Tools are grouped by domain and follow the naming pattern <product>_verb_noun (e.g. jira_search_issues, bitbucket_get_pull_request).

Every tool carries MCP annotations (read-only vs. destructive hints), and argument completions are provided for common identifiers (project keys, board IDs, repository slugs) so compatible clients can autocomplete them.

---

Quick start

Each package ships an interactive setup command that stores credentials in the most secure place your OS offers (macOS Keychain, or a 0600 file elsewhere). Run it once per product:

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

Setup prompts for host, API base path, default page size, and API token, then makes a live authenticated request to verify everything before saving — a wrong host or token is caught immediately. Leave the token blank to configure anonymous (unauthenticated) access on instances that allow it.

After setup, the server boots with zero environment variables — see Connecting a client.

Prefer explicit config? You can skip setup entirely and pass credentials via environment variables or a shared config file instead. See the Configuration reference.

Scripted / non-interactive setup

Setup accepts flags for CI or remote bootstrap (--help for the full list):

# Fully scripted
npx jira-datacenter-mcp setup --non-interactive --host jira.example.com --token "$JIRA_TOKEN"

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

In --non-interactive mode, missing values are resolved from existing configuration and the command exits 1 on the first validation failure — usable as a CI gate.

---

Connecting a client

Once setup has stored your credentials, the env block can be empty. The examples below pass credentials inline for clarity; drop the env entries if you ran setup.

Set *_HOST to a domain (+ optional port) without a protocol — https:// is assumed. To point at a non-standard path or force http://, use *_API_BASE_PATH with a full URL instead (the product-specific API suffix is appended automatically — don't include it).

Claude Desktop

Config file: ~/Library/Application Support/Claude/claude_desktop_config.json (macOS) · %APPDATA%\Claude\claude_desktop_config.json (Windows). Keep only the servers you need.

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

After running setup, this collapses to:

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

Claude Code

# Project scope (writes .mcp.json); add -s user for all projects
claude mcp add atlassian-jira-dc \
  -e JIRA_HOST=jira.example.com \
  -e JIRA_API_TOKEN=your-token \
  -- npx -y jira-datacenter-mcp

Swap -e JIRA_HOST=… for -e JIRA_API_BASE_PATH=https://jira.example.com/rest, or drop the -e flags entirely if you ran setup.

Cursor & other MCP clients

Any stdio MCP client works. Point it at the command npx -y <product>-datacenter-mcp and supply credentials through its env mechanism (or rely on setup). For remote/multi-client hosting, use the HTTP transport.

---

Authentication & tokens

Three modes, resolved per request:

• Personal Access Token (recommended) — set *_API_TOKEN. Sent as Authorization: Bearer <token>.
• Basic auth — set *_USERNAME + *_PASSWORD (for older instances without PATs). Takes precedence over a token if both are configured.
• Anonymous — set neither. No Authorization header is sent; works on instances that allow unauthenticated reads.

Generating a Personal Access Token

Give the token the minimum permissions it needs and copy it immediately — it is shown only once.

---

Configuration reference

Per-product variables

Each product reads its own prefix (JIRA_*, CONFLUENCE_*, BITBUCKET_*):

¹ Provide one of *_HOST or *_API_BASE_PATH. The API suffix is appended for you and must not be included: Jira /rest (+ /api/2), Confluence /rest/api, Bitbucket /rest (+ /api/latest).

Global variables

Precedence

At startup each config key is resolved by walking these sources in order and taking the first non-empty value:

Process env always wins, so you can override a stored credential for a single session. Keychain reads are cached once at startup — tool calls never shell out.

Shared config file

To reuse one set of credentials across several MCP hosts on a machine, put the *_HOST / *_API_TOKEN / … variables in one dotenv file and point every server at it with an absolute ATLASSIAN_DC_MCP_CONFIG_FILE:

JIRA_HOST=jira.example.com
JIRA_API_TOKEN=your-jira-token

CONFLUENCE_HOST=confluence.example.com
CONFLUENCE_API_TOKEN=your-confluence-token

BITBUCKET_HOST=bitbucket.example.com
BITBUCKET_API_TOKEN=your-bitbucket-token

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

---

Features

Where credentials are stored

setup splits secrets from non-secrets:

• macOS — token/password go to the login Keychain (service atlassian-dc-mcp); the copy in the home file is cleared after a successful write, so there's never a second copy in a less-secure place.
• Linux — home file ~/.atlassian-dc-mcp/<product>.env, mode 0600 (your user only).
• Windows — %USERPROFILE%\.atlassian-dc-mcp\<product>.env, inheriting your user-profile ACL.

Non-secret fields (host, base path, page size) always live in the home file.

Multiple instances (profiles)

To run two instances of the same product (e.g. two Jira sites), give each a --profile at setup and select it at launch with ATLASSIAN_DC_MCP_PROFILE:

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": {
    "jira-work":     { "command": "npx", "args": ["-y", "jira-datacenter-mcp"], "env": { "ATLASSIAN_DC_MCP_PROFILE": "work" } },
    "jira-personal": { "command": "npx", "args": ["-y", "jira-datacenter-mcp"], "env": { "ATLASSIAN_DC_MCP_PROFILE": "personal" } }
  }
}

A profile only changes which home file (<product>.<profile>.env) and Keychain account are used.

Transport: stdio & HTTP

By default every server speaks stdio — what local hosts like Claude Desktop expect. Set ATLASSIAN_DC_MCP_HTTP_PORT to a positive integer to serve the Streamable HTTP transport instead (for remote/multi-client access); the two are mutually exclusive per process.

ATLASSIAN_DC_MCP_HTTP_PORT=3000 npx jira-datacenter-mcp

The HTTP transport carries no auth of its own beyond the configured Atlassian credentials — put your own reverse proxy, TLS, and access control in front of it before exposing it beyond localhost.

Resilience

• Retries — transient failures (HTTP 429 and 5xx) are retried with exponential backoff and jitter (up to 3 attempts). A server-provided Retry-After header is honored (clamped to 30s) instead of the computed backoff. 4xx client errors are never retried.
• Response cap — tool results larger than ATLASSIAN_DC_MCP_MAX_RESPONSE_CHARS (default 100k chars) are truncated with a marker, so a single broad query can't flood the context window. Set 0 to disable.
• Bounded pagination — small, naturally finite lists (a project's versions, a page's labels) are auto-assembled into one result; open-ended searches (JQL/CQL, repo listings) stay single-page and agent-driven so they can't return an unbounded amount of data.
• Binary downloads — every download tool takes an optional absolute outputPath: with it the file is written to disk and only its metadata comes back, so size is irrelevant. Without it the bytes are returned as their own content block (an image, or a base64 resource blob), bypassing the response cap; anything over ATLASSIAN_DC_MCP_MAX_INLINE_BYTES is refused with a pointer to outputPath rather than truncated. That ceiling is 1 MiB for raster images, which a host decodes as a picture, and 256 KiB for everything else, whose base64 a host can only read as text.

Logging

All logs go to stderr as one JSON object per line ({"timestamp","level","message",…}), keeping stdout clean for the stdio protocol. Control verbosity with ATLASSIAN_DC_MCP_LOG_LEVEL:

ATLASSIAN_DC_MCP_LOG_LEVEL=debug npx jira-datacenter-mcp

---

Development

A pnpm workspace monorepo. Four packages under packages/: core (shared runtime) and one per product.

Prerequisites: Node.js ≥ 26 · pnpm (pinned to 11.9.0 via packageManager) · a reachable Atlassian DC/Server instance.

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

pnpm build          # build all packages (core first — others depend on its types)
pnpm typecheck      # tsc --noEmit across src + tests
pnpm lint           # ESLint (flat config, whole repo)
pnpm test           # unit tests (Vitest); the API client is mocked — no network

pnpm dev:jira       # watch-mode build for one product (also :confluence, :bitbucket)

Build or test a single package with --filter:

pnpm --filter jira-datacenter-mcp build
pnpm --filter jira-datacenter-mcp test

Live smoke test

Unit tests mock the API client, so they can't catch an auth/network/API-shape regression against a real instance. Each product can run an opt-in, read-only live test that skips itself (not a failure) when unconfigured:

cp packages/jira/.env.live.example packages/jira/.env.live
# edit .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

Versioning and publishing use Changesets; all four packages move in lockstep (a fixed group). Any behavior-changing PR should include one:

pnpm changeset

Commit the generated .changeset/*.md alongside your change. Merging the resulting "Version Packages" PR is what publishes to npm and the MCP Registry.

---

License

MIT