A2atlassian

🏢 a2atlassian

Agent-to-Atlassian

Give AI agents access to Jira and Confluence. Save credentials once, work from anywhere.

Jira + Confluence · read-only by default · pre-configured connections · compact TSV output

[PyPI] [Python] [License] [CI] [MCP Registry]

Quick Start · MCP Tools · Security · Comparison · Setup

Agent: "What's the status of PROJ-42? Add a comment with the progress update."  ↓a2atlassian → get issue, add comment, transition to In Progress  ↓Agent: "Done — PROJ-42 updated and moved to In Progress."

Why a2atlassian?

Existing Atlassian MCP servers (Rovo, sooperset) require Docker, .env files, and mcp-remote bridges. They dump 72 tools into agent context and have known quirks that silently fail. a2atlassian fixes all of that:

• No Docker — pip install a2atlassian and you're done
• Pre-configured connections — define projects in .mcp.json with --register, agent works immediately
• Read-only by default — write access is opt-in per connection
• Connection scoping — --scope limits which projects an agent can see
• Compact output — TSV for lists (30-60% fewer tokens), JSON for single entities
• Dynamic tool loading — MCP clients that support deferred tools (e.g., Claude Code) load tools on demand, keeping context lean
• Error enrichment — bad field names get suggestions, JQL typos get corrections, quirks get auto-fixed
• Secrets stay in env — ${ATLASSIAN_TOKEN} in configs, expanded only at runtime

Scope today: full Jira surface (issues, comments, sprints, boards, worklogs, links, versions, fields, watchers, projects) and Confluence core (pages CRUD, search, metadata-only writes).

Quick Start

# Recommended — installs globally as a CLI tooluv tool install a2atlassian
# Or with pippip install a2atlassian

As an MCP Server (recommended)

Claude Code (with pre-configured connection):

claude mcp add -s user a2atlassian -- uvx --from a2atlassian a2atlassian-mcp \  --register myproject https://mysite.atlassian.net [email protected] '${ATLASSIAN_TOKEN}'

Claude Code (minimal — agent calls login on demand):

claude mcp add -s user a2atlassian -- uvx --from a2atlassian a2atlassian-mcp

Claude Desktop / Cursor / any MCP client (.mcp.json):

{  "mcpServers": {    "a2atlassian": {      "command": "uvx",      "args": [        "--from", "a2atlassian", "a2atlassian-mcp",        "--register", "myproject", "https://mysite.atlassian.net",        "[email protected]", "${ATLASSIAN_TOKEN}"      ],      "env": {        "ATLASSIAN_TOKEN": "your-api-token-here"      }    }  }}

Multiple projects:

{  "args": [    "--from", "a2atlassian", "a2atlassian-mcp",    "--register", "myproject", "https://mysite.atlassian.net", "[email protected]", "${TOKEN_A}",    "--register", "personal", "https://personal.atlassian.net", "[email protected]", "${TOKEN_B}"  ]}

Scoped connections (limit agent to specific saved projects):

{  "args": ["--from", "a2atlassian", "a2atlassian-mcp", "--scope", "myproject"]}

--register creates ephemeral in-memory connections (process lifetime, no files written). --scope filters which saved connections are visible. Both limit blast radius.

As a CLI

# Save a connection (validates by calling /myself)a2atlassian login -c myproject \  --url https://mysite.atlassian.net \  --email [email protected] \  --token "$ATLASSIAN_TOKEN"
# Same, pulling the token from 1Password via `op`a2atlassian login -c myproject \  --url https://mysite.atlassian.net \  --email [email protected] \  --token "op://Personal/Atlassian/token"
# Enable writesa2atlassian login -c myproject \  --url https://mysite.atlassian.net \  --email [email protected] \  --token "$ATLASSIAN_TOKEN" \  --no-read-only
# List / remove connectionsa2atlassian connectionsa2atlassian logout -c myproject

Tokens accept three forms: literal value, ${ENV_VAR} reference, or op://vault/item/field (resolved via the 1Password CLI at runtime).

MCP Tools

Connection Management

Jira — Read

Jira — Write (requires read-write connection)

Confluence — Read

Confluence — Write (requires read-write connection)

Output Formats

All tools accept a format parameter:

List responses use a compact TSV-style format (header row + tab-separated values) inspired by TOON. This is the same approach a2db uses — column names appear once, then just values. For a 50-issue search result, this typically saves 40-60% of tokens compared to JSON.

TSV example (search results):

# search (23 results, 50ms, truncated: False)key	summary	assignee	statusPROJ-142	Fix auth timeout	Alice Smith	In ProgressPROJ-141	Add search filters	Bob Jones	To Do

JSON example (single issue):

{  "data": {"key": "PROJ-142", "fields": {"summary": "Fix auth timeout", ...}},  "count": 1,  "truncated": false,  "time_ms": 85}

Error Enrichment

When something fails, a2atlassian tells the agent what to do:

Field 'asignee' does not existDid you mean: assignee?

Connection 'myproject' is read-only.Run: a2atlassian login -p myproject --read-only false

Quirks handled automatically:

• Assignee requires display name (not 712020: account IDs) — auto-detected with hint
• Parent field must be plain string — {"key": "PROJ-14"} normalized to "PROJ-14" silently
• Issue type conversion not supported via API — clear Jira UI instructions provided

Security

Read-Only by Default

Every connection starts read-only. Write tools check the connection flag before executing:

Connection 'myproject' is read-only.Re-run 'a2atlassian login -p myproject --read-only false' to enable writes.

The human operator controls write access — not the agent.

Credential Storage

Connections saved via login go to ~/.config/a2atlassian/connections/ as TOML files:

• File permissions: 0600 (owner read/write only)
• ${ATLASSIAN_TOKEN} syntax — env var references stored literally, expanded at runtime
• No secrets in output — list_connections shows project name, URL, and mode — never tokens
• Ephemeral mode — --register keeps credentials in memory only, never written to disk

Connection Scoping

Use --scope to limit which saved connections a specific MCP instance can access:

# Project config — only myproject visible, even if other connections are saveduvx --from a2atlassian a2atlassian-mcp --scope myproject

Project-level MCP configs (.claude/mcp.json) override global configs — each repo sees only its own connections.

Rate Limiting

Built-in retry with exponential backoff for Atlassian's rate limits (429) and transient server errors (500). Two retries at 1s and 3s intervals before surfacing the error.

Comparison

Roadmap

Shipped: Jira full surface (v0.3.0) · Confluence core + markdown-to-storage with full CommonMark + GFM fidelity (v0.4.0, v0.5.2) · 1Password op:// token refs (v0.5.1) · metadata-only Confluence writes + preserve-on-omit body semantics (v0.5.2).

Next: confluence_delete_page, Confluence comments + attachments, Confluence integration-test path. Backlog in TODO.md.

Setup by Environment

Local (macOS / Linux)

# Recommendeduv tool install a2atlassian
# Or with pippip install a2atlassian
# CLIa2atlassian login -p myproject --url https://mysite.atlassian.net --email [email protected] --token "$TOKEN"
# Or add as MCP server (see Quick Start)

CI / Automation

uv tool install a2atlassian
# Pre-configured — no login neededuvx --from a2atlassian a2atlassian-mcp --register ci https://mysite.atlassian.net [email protected] "${CI_ATLASSIAN_TOKEN}"

Development

make bootstrap   # Install deps + pnpm + git hooksmake check       # Lint + test + coverage-diff + security (full gate)make test        # Tests with coveragemake lint        # agent-harness + jscpd + actionlint (never modifies files)make fix         # Auto-fix + lintmake similar     # Advisory: report similarly-named functions/classes

Linters: ruff + ty (via agent-harness), yamllint, jscpd (copy-paste detection via pnpm), actionlint (GitHub Actions workflows). Pre-commit hooks run agent-harness fix + lint on every commit. Install pnpm and actionlint via brew install pnpm actionlint.

License

Apache 2.0

_{🏢 Agent-first Atlassian access since 2025.}

_{Built by Denis Tomilin}