매뉴얼

Claude 연동

Claude 연동

v1.11.0+

Claude 연동은 Claude 데스크톱 앱(Windows·macOS)에 확장 프로그램을 추가해 Claude와의 대화로 GeckoFlag를 조작하는 기능입니다. 이슈·프로젝트·Wiki·노트의 검색·조회·생성·업데이트와 Gantt 차트 Excel 내보내기를 할 수 있습니다. 확장 프로그램은 사용자의 PC에서 실행되며 사용자의 GeckoFlag와만 직접 통신합니다. 모든 작업은 API 토큰 소유자의 사용자 권한으로 이루어집니다.

관리자 설정

  1. 1사이드 메뉴에서 설정을 열고 Claude 연동 카드의 편집을 클릭합니다.설정 화면. “Claude Integration” 카드가 빨간 테두리로 표시되어 있다
  2. 2Claude 연동 사용을 켭니다(초기 상태는 꺼져 있음). Claude가 생성·변경까지 하게 하려면 쓰기 허용도 켜고 저장합니다. 쓰기를 허용하지 않으면 모든 토큰이 읽기 전용이 됩니다.Claude 연동 설정 화면. “Enable Claude integration”, “Allow writing” 체크 상자가 빨간 테두리로 표시되어 있고, 아래에 허가한 사용자 수와 API 토큰 수가 표시되어 있다
  3. 3사용자 목록에서 대상 사용자의 편집을 열고 Claude 연동(API) 이용 허용을 켠 뒤 업데이트를 클릭합니다. “AI 등록 허용”과는 별도의 설정입니다. 허가를 해제하면 해당 사용자의 API 토큰이 모두 삭제됩니다.사용자 편집 화면. 사이드 메뉴의 “Users”와 “Allow Claude integration (API)” 체크 상자가 빨간 테두리로 표시되어 있다

API 토큰 만들기

  1. 1사이드 메뉴에서 프로필을 열고 API 토큰 항목에서 토큰 이름·유효 기간(30일·90일·365일·무기한, 기본값은 90일)·권한(읽기 또는 읽기 및 쓰기)을 지정해 토큰을 만듭니다.프로필 화면의 “API Tokens (Claude Integration)” 항목. Token name·Expires in·Permission 입력란이 빨간 테두리로 표시되어 있다
  2. 2표시된 토큰(gfk_ 로 시작하는 문자열)을 복사합니다. 토큰은 만든 직후 한 번만 표시됩니다. 같은 항목에 표시되는 “확장 프로그램에 입력할 URL”도 메모해 둡니다.
  • 토큰은 1인당 5개까지 만들 수 있으며, 더 이상 쓰지 않는 토큰은 프로필에서 언제든지 삭제할 수 있습니다.
  • 토큰을 만들면 본인에게 알림 메일이 발송됩니다. 비밀번호를 변경하면 해당 사용자의 토큰이 모두 삭제됩니다.

Claude 데스크톱 앱에 설정하기

  1. 1Claude 데스크톱 앱의 Settings(설정) → Extensions(확장 프로그램)를 열고, GeckoFlag 확장 프로그램 파일(.mcpb)을 드래그 앤 드롭한 뒤 Install을 클릭합니다. 파일을 더블클릭하거나 Advanced settings에서도 설치할 수 있습니다. 확장 프로그램 파일은 GeckoFlag 구매 후 받을 수 있는 다운로드 파일에 포함되어 있습니다.
  2. 2설정 화면에서 다음 항목을 입력하고 Save를 클릭합니다.
    • GeckoFlag URL(필수): 메모해 둔 URL. https://가 필요합니다(http://는 localhost·*.test·*.local만 가능).
    • API token(필수): 복사한 토큰. 마스킹되어 저장됩니다.
    • Export folder(선택): Gantt 차트 Excel의 저장 위치. 비워 두면 다운로드 폴더에 저장됩니다.
    GeckoFlag 확장 프로그램 설정 화면. GeckoFlag URL, API token, Export folder 입력란이 있다
  3. 3Claude에게 “GeckoFlag에 연결되어 있는지 확인해 줘”라고 요청합니다. 토큰 소유자, GeckoFlag 버전, 쓰기 가능 여부가 표시되면 완료입니다.

화면과 함께 보는 자세한 절차는 Claude 연동 이용 절차를 참고하세요. 쓰기 작업은 Claude의 확장 프로그램 설정에서 “매번 확인”으로 해 두는 것을 권장합니다.

할 수 있는 일

  • 이슈: 검색(프로젝트·상태·담당자·등록자·우선순위·키워드·마감일·상위 이슈), 상세와 댓글 조회, 생성(상위 이슈·알림 대상 지정 가능), 항목 변경, 댓글 작성, 상태 변경.
  • 프로젝트: 목록·상세 조회, 생성(게스트 제외), 이름·설명·소유자·기간 변경과 완료/미완료 전환, 멤버 추가·제거(소유자·관리자).
  • Wiki: 조회, 제목·본문 다시 쓰기, 끝에 내용 추가(프로젝트 멤버·관리자).
  • 노트: 내 노트의 목록 보기·검색·조회·생성·다시 쓰기·추가 작성.
  • 마스터: 이슈 유형·상태·우선순위·직책(부서) 추가와 이름·색상 변경(관리자).
  • Gantt 차트: 프로젝트의 이슈(최대 5,000건)를 Excel 파일로 만들어 PC에 저장. 기간이 120일을 넘으면 1열 = 1주가 됩니다.
  • 사용자 검색: 이름으로 사용자 찾기(ID와 역할만 반환하며, 이메일 주소는 반환하지 않습니다).

이슈는 “WEB-12” 같은 키로 지정할 수 있습니다. 쓰기에는 “읽기 및 쓰기” 토큰과 사이트의 “쓰기 허용”이 모두 필요합니다.

할 수 없는 일·한도

  • 삭제(프로젝트·이슈·댓글·마스터·Wiki·노트), 댓글 편집, 이미지·파일 첨부 및 조회, 프로젝트 키 변경, 마스터 순서 변경은 할 수 없습니다.
  • 사용자 추가·편집, 사이트 설정 변경, Kanban 보드·북마크·알림 설정 조작, 다른 사용자의 노트 조회(관리자도 불가)는 할 수 없습니다.
  • 쓰기는 한 번에 1건입니다. 여러 건은 Claude가 1건씩 실행합니다. 응답 대기 시간은 30초이며, 쓰기는 중복 등록을 막기 위해 자동으로 재시도하지 않습니다.
  • 이슈 제목은 50자 이내, 마스터 이름은 20자 이내(각 10개까지, 색상은 8가지 중 선택)입니다. Wiki 본문은 전체 65,535바이트, 노트 본문은 1,000,000바이트까지입니다.
  • Claude가 읽는 본문은 설명·Wiki·노트가 8,000자, 댓글이 2,000자를 넘으면 생략됩니다. 생략된 본문은 다시 쓰지 않고 추가 작성을 안내합니다.
  • 검색·목록은 1페이지에 50건까지입니다. 횟수 제한은 토큰 1개당 1분에 60회입니다.
  • Claude 데스크톱 앱이 PC에서 실행 중일 때만 사용할 수 있습니다.

기록과 알림 메일

  • 이슈 항목을 변경하면 화면에서 편집할 때와 마찬가지로 기록 댓글이 남지 않고 메일도 발송되지 않습니다. 기록을 남기고 싶다면 “댓글로 변경해 줘”라고 요청합니다.
  • 댓글로 상태 등을 변경하면 화면과 마찬가지로 기록이 남고, 모든 댓글 알림을 받는 멤버에게 메일이 발송됩니다.
  • 이슈를 만들 때 메일을 받는 사람은 알림 대상으로 지정한 멤버뿐입니다. 프로젝트를 만들 때는 멤버에게 초대 메일이 발송됩니다(나중에 추가한 경우에는 발송하지 않습니다).
  • 작업은 토큰 소유자의 작업으로 기록되며 “Claude 경유” 표시는 없습니다.

보안과 데이터 취급

Claude 연동이 꺼져 있으면 API는 존재하지 않는 URL과 같이 취급됩니다(404). 권한이 없는 프로젝트나 이슈도 “존재하지 않는” 것으로 취급됩니다. 토큰은 서버에 해시만 저장하며, API에도 GeckoFlag의 IP 주소 접근 제한이 적용됩니다. Claude가 읽은 이슈·Wiki·노트의 내용은 대화의 일부로 Anthropic에 전송됩니다. 사내 규정이나 거래처와의 계약에서 외부 서비스로의 전송이 제한되어 있지 않은지 도입 전에 확인하세요. 연결이 잘 되지 않을 때는 문제가 생겼을 때를 참고하세요.