atlassian-sdk-py

Atlassian REST API를 직접 호출하는 Python async SDK. Jira + Confluence를 하나의 패키지로 지원합니다.

acli 바이너리 불필요 — httpx로 REST API 직접 호출

설치

pip install atlassian-sdk-py

환경변수

ATLASSIAN_SITE=your-site.atlassian.net
ATLASSIAN_EMAIL=user@example.com
ATLASSIAN_API_TOKEN=your-api-token
PYACLI_DEFAULT_PROJECT=WNVO
PYACLI_EPIC_MAP=frontend:WNVO-9,backend:WNVO-23,ai:WNVO-24

Jira 사용법

import asyncio
from atlassian_sdk import JiraClient

async def main():
    client = JiraClient()

    # 프로젝트 목록 조회
    projects = await client.list_projects()

    # 에픽 이름으로 이슈 생성 (epic map 사용)
    issue = await client.create_issue(
        summary="로그인 에러 수정",
        epic="frontend",            # → WNVO-9 밑에 생성
        labels=["bug", "backend"],
    )
    print(issue.key)  # WNVO-111
    print(issue.url)  # https://site.atlassian.net/browse/WNVO-111

    # 이슈 조회
    issue = await client.get_issue("WNVO-111")

    # JQL 검색
    issues = await client.search_issues(
        jql="project = WNVO AND status = 'To Do'",
    )

    # 상태 변경
    await client.transition_issue("WNVO-111", status="완료")

    # 댓글
    await client.add_comment("WNVO-111", body="수정 완료")
    comments = await client.list_comments("WNVO-111")

asyncio.run(main())

Confluence 사용법

from atlassian_sdk import ConfluenceClient

async def main():
    client = ConfluenceClient()

    # 스페이스 목록
    spaces = await client.list_spaces()

    # 페이지 생성
    page = await client.create_page(
        space_id="12345",
        title="회의록 2024-01-15",
        body="<h1>회의 내용</h1><p>안건 논의</p>",
    )

    # 페이지 조회 / 수정
    page = await client.get_page("67890")
    updated = await client.update_page(
        "67890",
        title="회의록 (수정)",
        body="<p>수정된 내용</p>",
        version_number=2,
    )

    # 하위 페이지 / 댓글
    children = await client.get_child_pages("67890")
    await client.add_footer_comment("67890", body="확인했습니다")

    # CQL 검색
    results = await client.search(cql="type=page AND space=DEV")

Jira 계층 구조

Project (WNVO)
├── [에픽] 기능구현-프론트 1차          ← parent 없이 생성
│   ├── [작업] 로그인 에러 수정         ← parent = 에픽 키
│   │   ├── [하위작업] UI 구현         ← parent = 작업 키
│   │   └── [하위작업] API 연동
│   └── [작업] 회원가입 구현
└── [에픽] 기능구현-백엔드 1차

Pydantic 입력 모델

파라미터가 많을 때 Request 모델을 사용할 수 있습니다:

from atlassian_sdk import JiraClient, CreateIssueRequest

client = JiraClient(project="WNVO")

req = CreateIssueRequest(
    summary="복잡한 이슈",
    description="상세 설명",
    type="Bug",
    assignee="user-account-id",
    labels=["bug", "urgent"],
    parent="WNVO-9",
)
issue = await client.create_issue(request=req)

FastAPI 에러 자동 보고

from fastapi import FastAPI, Request
from fastapi.responses import JSONResponse
from atlassian_sdk import JiraClient
import traceback

app = FastAPI()
client = JiraClient()

@app.middleware("http")
async def error_reporting(request: Request, call_next):
    try:
        return await call_next(request)
    except Exception as exc:
        tb = "".join(traceback.format_exception(type(exc), exc, exc.__traceback__))
        issue = await client.create_issue(
            summary=f"[AUTO-BUG] {type(exc).__name__}: {exc}",
            description=f"Endpoint: {request.method} {request.url.path}",
            issue_type="버그",
            epic="backend",
        )
        await client.add_comment(issue.key, body=tb)
        return JSONResponse(status_code=500, content={"jira": issue.key})

MCP 서버

Claude Desktop/Claude Code에서 Jira + Confluence를 사용할 수 있는 MCP 서버가 포함되어 있습니다.

{
  "mcpServers": {
    "atlassian-sdk": {
      "command": "uvx",
      "args": ["--from", "atlassian-sdk-py", "atlassian-sdk-mcp", "--", "--env-file", ".env"]
    }
  }
}

--env-file 옵션으로 환경변수 파일 경로를 지정합니다. .env, .env.local 등 원하는 파일을 사용할 수 있습니다.

# .env
ATLASSIAN_SITE=your-site.atlassian.net
ATLASSIAN_EMAIL=user@example.com
ATLASSIAN_API_TOKEN=your-api-token
PYACLI_DEFAULT_PROJECT=WNVO
PYACLI_EPIC_MAP=frontend:WNVO-9,backend:WNVO-23,ai:WNVO-24

--env-file을 생략하면 셸 환경변수 또는 .mcp.json의 env 필드에서 읽습니다.

제공 도구 (20개):

• Schema 도구: list_methods, get_method_info, get_models
• Jira 도구: list_projects, list_issue_types, get_issue, search_issues, create_issue, transition_issue, add_comment, list_comments
• Confluence 도구: create_page, get_page, update_page, list_spaces, get_pages_in_space, get_child_pages, get_footer_comments, add_footer_comment, search_confluence

인증

Basic Auth: email + API token → Authorization: Basic base64(email:token)

기술 스택

• Python 3.11+
• httpx (async HTTP)
• Pydantic v2
• MCP SDK
• Poetry

라이선스

MIT