atlassian-buddy

MCP server that connects Claude to Jira and Confluence. Engineers can research spikes, generate technical solutions with Mermaid architecture diagrams, write Confluence docs, and create Jira epic + story breakdowns through natural conversation — no Anthropic API key required.

Features

• Research — search Confluence and Jira before generating anything
• Design — produce Mermaid architecture/flow diagrams as part of every confluence doc
• Write — create or update Confluence pages (markdown + Mermaid → Confluence storage format)
• Ticket — create Jira Epics, Stories with acceptance criteria, and Tasks; supports both next-gen and classic projects
• Zero LLM cost — Claude itself provides all intelligence; no separate AI API key needed

Installation

Choose your preferred installer:

# pip
pip install atlassian-buddy

# pipx (recommended — isolated environment, auto-manages PATH)
pipx install atlassian-buddy

# uv
uv tool install atlassian-buddy

Setup

Step 1 — Create ~/.atlassian_buddy.toml

Create ~/.atlassian_buddy.toml in your home directory with your Atlassian details:

# macOS / Linux
touch ~/.atlassian_buddy.toml

[atlassian]
base_url = "https://yourorg.atlassian.net"
email    = "you@yourorg.com"

[confluence]
# If your Confluence is on a different domain than Jira, set this:
# base_url = "https://yourorg-docs.atlassian.net"
space_key      = "ENG"
parent_page_id = "123456"

[jira]
project_key        = "PLAT"
epic_issue_type    = "Epic"
story_issue_type   = "Story"
task_issue_type    = "Task"
default_label      = "spike"
story_points_field = "customfield_10016"
epic_link_field    = "customfield_10014"

[tickets]
story_point_scale = [1, 2, 3, 5, 8, 13]

Tip: Config is also discovered automatically in your project root or any parent directory up to the git root — useful when running atlassian-buddy from a specific repo. The search order is: current directory → git root walk-up → ~/.atlassian_buddy.toml.

Org-specific required fields

Some Jira projects enforce mandatory custom fields (e.g. Account, Tier, Work type). Add them under [jira.required_fields] and they will be merged into every ticket created:

[jira.required_fields]
customfield_11139 = 15                  # plain integer (check your field type)
customfield_11518 = { id = "12203" }    # single select
customfield_11664 = [{ id = "13089" }]  # multi-select (array)

To find the correct field IDs and allowed values for your project, call the Jira create-meta API:

GET /rest/api/3/issue/createmeta?projectKeys=PROJ&issuetypeNames=Epic&expand=projects.issuetypes.fields

Step 2 — Set your API token

Generate an Atlassian API token at https://id.atlassian.com/manage-profile/security/api-tokens and export it:

export ATLASSIAN_API_TOKEN="your-token-here"

Never put the token in .atlassian_buddy.toml — it is read exclusively from the environment.

Connect to Claude

atlassian-buddy works with both Claude Desktop (GUI app) and Claude Code (CLI). Follow the guide for whichever you use — or both.

Option A — Claude Desktop

Step 1 — Find the config file

Step 2 — Find your binary path

Run this in your terminal to get the exact path to use in the config:

which atlassian-buddy

Step 3 — Add atlassian-buddy to mcpServers

Use the block for whichever installer you used. All blocks have the same structure — the only difference is the command path.

pip

{
  "mcpServers": {
    "atlassian-buddy": {
      "command": "/Users/YOU/.local/bin/atlassian-buddy",
      "env": {
        "ATLASSIAN_API_TOKEN": "your-token-here"
      }
    }
  }
}

macOS path may be ~/Library/Python/3.x/bin/atlassian-buddy. Run which atlassian-buddy to confirm.

pipx

{
  "mcpServers": {
    "atlassian-buddy": {
      "command": "/Users/YOU/.local/bin/atlassian-buddy",
      "env": {
        "ATLASSIAN_API_TOKEN": "your-token-here"
      }
    }
  }
}

Confirm the path with: pipx environment atlassian-buddy | grep -i bin

uv

{
  "mcpServers": {
    "atlassian-buddy": {
      "command": "/Users/YOU/.local/bin/atlassian-buddy",
      "env": {
        "ATLASSIAN_API_TOKEN": "your-token-here"
      }
    }
  }
}

Confirm the path with: uv tool dir --bin — the binary lives in that directory.

Step 4 — Restart Claude Desktop

Quit and reopen the app. A hammer icon (🔨) in the toolbar confirms the tools are active.

Option B — Claude Code (CLI)

Step 1 — Find your binary path

which atlassian-buddy

Step 2 — Add atlassian-buddy globally

Run the command for whichever installer you used. Replace the path with the output of which atlassian-buddy above.

pip

claude mcp add atlassian-buddy ~/.local/bin/atlassian-buddy -s user -e ATLASSIAN_API_TOKEN="your-token-here"

macOS path may be ~/Library/Python/3.x/bin/atlassian-buddy. Use which atlassian-buddy to confirm.

pipx

claude mcp add atlassian-buddy ~/.local/bin/atlassian-buddy -s user -e ATLASSIAN_API_TOKEN="your-token-here"

Confirm the exact path with: pipx environment atlassian-buddy | grep -i bin

uv

claude mcp add atlassian-buddy ~/.local/bin/atlassian-buddy -s user -e ATLASSIAN_API_TOKEN="your-token-here"

Confirm the exact path with: uv tool dir --bin

Step 3 — Verify the connection

claude mcp list

You should see:

atlassian-buddy: /Users/YOU/.local/bin/atlassian-buddy  - ✓ Connected

Step 4 — Start a new Claude Code session

MCP servers are loaded at session start. Open a fresh session in any directory and atlassian-buddy tools will be available automatically.

Example conversations

Start a session by invoking the workflow prompt at the top of your conversation:

/mcp__atlassian-buddy__buddy_workflow

Then talk naturally:

• "I need to spike on replacing our job queue with Temporal. Research what we have, design a solution with a diagram, write a spike doc in Confluence under the Platform space, then create an epic and stories in the PLAT project."
• "Search Confluence for our auth service architecture and summarise what you find."
• "Break down the confluence doc you just wrote into Jira tickets — 1 epic, stories with acceptance criteria, fibonacci points."
• "What Jira tickets are open in PLAT related to observability?"

Tools

Configuration reference

All fields in .atlassian_buddy.toml:

Contributing

git clone https://github.com/de-cryptor/atlassian-buddy
cd atlassian-buddy
python -m venv .venv && source .venv/bin/activate
pip install -e ".[dev]"
pytest

License

MIT — see LICENSE.