Claude·LLM과 연동하기 (MCP)

@peoplenexteam/toodoori-mcp는 Claude 같은 LLM이 toodoori의 할 일 관리를 직접 수행하도록 해주는 MCP(Model Context Protocol) 서버입니다. toodoori API를 얇게 감싼 stdio 서버로, 개인 액세스 토큰(PAT)을 달아 toodoori 서버의 인증·권한 검사를 그대로 거칩니다.

연동하면 Claude에게 이렇게 말할 수 있습니다:

“이번 주 마감인 작업 보여줘”, “이 프로젝트에 ‘리뷰 요청’ 작업 만들어줘”, “끝낸 작업들 완료로 옮겨줘”

무엇이 필요한가요?

toodoori 계정과 개인 액세스 토큰(PAT)
MCP를 지원하는 클라이언트 — Claude Desktop 또는 Claude Code
Node.js (npx 실행용)

1단계 — 개인 액세스 토큰(PAT) 발급

MCP 서버는 PAT로 사용자를 대신해 API를 호출합니다.

toodoori.com에 로그인합니다.
마이페이지 → 액세스 토큰 탭으로 이동합니다.
토큰 발급을 눌러 이름과 필요한 권한(스코프)만 선택하고 만료 기간을 정합니다.
발급된 토큰(tdr_pat_...)을 복사합니다.

⚠️ 토큰은 발급 직후 한 번만 표시됩니다. 비밀번호처럼 안전한 곳(시크릿 매니저 등)에 보관하세요. 다시 볼 수 없습니다.

최소 권한 원칙: 읽기만 필요하면 read 스코프만 선택하세요. 작업 생성·수정이 필요할 때만 해당 리소스의 write를 켜면 됩니다.

2단계 — Claude에 등록하기

사용하는 도구에 맞춰 한 번만 등록하면 됩니다.

Claude Desktop (가장 쉬움)

claude_desktop_config.json에 아래를 붙여넣고, tdr_pat_...만 1단계에서 복사한 내 토큰으로 바꾸세요(주소는 그대로).

{
  "mcpServers": {
    "toodoori": {
      "command": "npx",
      "args": ["-y", "@peoplenexteam/toodoori-mcp"],
      "env": {
        "TOODOORI_PAT": "tdr_pat_...",
        "TOODOORI_API_BASE": "https://api.toodoori.com"
      }
    }
  }
}

저장 후 Claude Desktop을 재시작하면 toodoori 도구가 나타납니다.

이 설정 파일은 내 컴퓨터 개인 폴더(~/Library/Application Support/Claude/)에 있어 코드 저장소(git)에는 올라가지 않습니다. 다만 토큰이 평문으로 저장되니, 꼭 필요한 권한만·짧은 만료로 발급하고 의심되면 즉시 폐기하세요.

Claude Code (터미널 사용자)

⚠️ 토큰을 명령에 직접 넣어 claude mcp add만 하면 그 프로젝트에서만 동작하고, 토큰이 파일에 남아 실수로 git에 올라갈 수 있습니다. 아래처럼 ① 토큰을 셸 환경변수로 두고 ② 사용자 범위(--scope user) 로 등록하면, 모든 프로젝트에서 쓰면서 토큰이 어떤 설정 파일에도 저장되지 않습니다.

① 토큰을 셸 프로필에 추가 (~/.zshrc 또는 ~/.bashrc):

export TOODOORI_PAT="tdr_pat_..."
export TOODOORI_API_BASE="https://api.toodoori.com"

추가한 뒤 터미널을 새로 열거나 source ~/.zshrc를 실행하세요.

② 사용자 범위로 등록 (토큰을 명령에 넣지 않습니다):

claude mcp add --scope user toodoori -- npx -y @peoplenexteam/toodoori-mcp

등록 정보는 홈 디렉토리(~/.claude.json)에 저장되며 토큰은 포함되지 않습니다. MCP 서버가 실행될 때 위 환경변수를 그대로 물려받습니다. (환경변수가 설정된 터미널에서 claude를 실행하세요.)

팀과 공유할 때: 토큰을 넣은 채로 --scope project(저장소의 .mcp.json)를 쓰지 마세요. 공유가 필요하면 토큰 없는 설정만 커밋하고 각자 셸 환경변수로 토큰을 넣도록 안내하세요. .mcp.json·.env는 .gitignore에 추가합니다.

무엇을 할 수 있나요?

MCP 서버는 24개의 도구를 제공합니다.

읽기: 프로젝트·보드·스테이지 조회, 전역/프로젝트 작업 검색, 작업 상세, 라벨·하위 프로젝트 조회, 첨부 읽기
작업 관리: 작업 생성·수정·이동(단건/다건)·보관·삭제, 라벨 변경, 체크리스트 항목 추가·수정, 노트 작성, 첨부 업로드
구성 관리: 라벨 생성, 하위 프로젝트 수정

부여한 스코프 범위 안에서만 동작합니다. 예를 들어 tasks:read만 있는 토큰은 작업을 조회할 수 있지만 생성·수정은 거부(403)됩니다.

알아두면 좋은 규약

마감일은 expectedEnd로 표현됩니다.
작업 본문·회고·노트는 마크다운 문자열로 주고받습니다.
프로젝트/하위 프로젝트 ID는 인코딩된 문자열이라 임의로 만들지 말고 목록 도구가 돌려준 id를 그대로 사용합니다.
오류는 { error, code, status } 형태로 반환되어 LLM이 code를 보고 스스로 교정합니다.

보안 주의

PAT는 헤더 전용입니다. URL이나 코드 저장소에 노출하지 마세요.
필요한 최소 권한만 부여하고, 만료 기간을 짧게 유지하세요.
토큰이 유출됐다면 마이페이지 → 액세스 토큰에서 즉시 폐기하거나 회전(새 토큰 발급 + 기존 즉시 무효화)하세요.

다음 단계

연동을 마쳤다면, Claude에게 자연어로 작업을 맡겨 보세요. 매일 반복하던 정리·이동·생성을 대화 한 줄로 처리하며, 보드는 늘 최신 상태로 유지됩니다.