Workel MCP Server

Workel 공식 Model Context Protocol 서버입니다. Workel Public API v1(https://developer.workel.com)의 얇은 무상태 클라이언트로, Workel 워크스페이스를 AI 에이전트(Claude, OpenAI Agents SDK, 또는 기타 MCP를 지원하는 클라이언트)에 잘 정의된 소수의 도구 집합으로 노출합니다. 실제로 중요한 모든 규칙(이 키가 볼 수 있는 것, 쓸 수 있는 것, 얼마나 빨리 쓸 수 있는지)은 Workel API 자체에 있으며, 이 패키지는 키가 이미 갖고 있지 않은 권한을 보유하지 않습니다. 동일한 키로 만든 curl 요청은 이 서버가 할 수 있는 것과 정확히 동일한 작업을 수행할 수 있으며, 그 이상은 불가능합니다.

클라이언트별 전체 설정(Claude Desktop, Claude Code, 프로젝트 범위 .mcp.json, OpenAI Agents SDK)은 Workel 개발자 문서를 참조하세요.

Claude를 사용 중이라면 이 패키지가 필요하지 않을 수 있습니다

Workel은 호스팅 MCP 서버를 운영합니다. Claude에서 설정 → 커넥터 → 사용자 지정 커넥터 추가로 추가하세요:

https://mcp.workel.com/mcp

Workel에 로그인하고 워크스페이스 하나를 선택하면 연결됩니다. 설치도, 구성 파일도, API 키도 필요 없습니다. 키를 볼 일도 없고 Claude도 볼 수 없습니다. 인증하려면 선택한 워크스페이스의 소유자 또는 관리자여야 하며, 연결은 모든 요청에서 다시 확인되므로 해당 역할을 잃으면 키를 기억해서 해지할 필요 없이 연결이 끊깁니다.

프로젝트, 작업, 댓글, 이벤트, 멤버를 읽을 수 있으며(작업의 표지 이미지, 첨부 파일, 전체 기록 포함), 작업, 댓글, 이벤트를 생성하고 기존 작업을 업데이트할 수 있습니다(이름 변경, 날짜 및 우선순위 변경, 칼럼 및 프로젝트 간 이동, 담당자 변경). 삭제는 불가능하며 파일 업로드도 불가능합니다. 읽기 및 쓰기 권한은 동의 화면에 별도로 표시되므로 나중에 발견하는 대신 명시적으로 승인하게 됩니다.

워크스페이스 두 개 이상 연결

연결 하나는 워크스페이스 하나를 다룹니다. 그 이유는 그 뒤에 있는 자격 증명이 해당 워크스페이스에 바인딩되어 있기 때문입니다. 두 번째 워크스페이스에 접근하려면 커넥터를 다시 추가하고 다른 워크스페이스를 선택하세요. 각 연결은 별도로 등록되므로 공존하며, 각각 워크스페이스 이름(workel — Acme)으로 표시되어 구분할 수 없는 동일한 항목으로 나타나지 않습니다.

주의할 점 하나: 기존 연결을 다시 인증하면 이동되며 추가되지 않습니다. 이미 추가한 커넥터에서 다시 동의를 거치면 해당 자격 증명이 교체되고 이전 자격 증명이 비활성화되므로 해당 연결은 선택한 워크스페이스로 전환됩니다. 둘 다 원한다면 기존 커넥터를 다시 인증하는 대신 새 커넥터를 추가하세요.

Related MCP server: Google Workspace MCP Server

직접 실행하기

이 패키지는 호스팅 서버가 다루지 않는 경우를 위한 것입니다: Claude Code, CI 에이전트, OpenAI Agents SDK — 프로세스를 직접 실행하고 자격 증명을 보유하려는 모든 곳. 아래의 모든 내용은 이에 관한 것입니다.

이 패키지는 여러 워크스페이스를 다르게, 그리고 이 사용 사례에 더 잘 처리합니다: WORKEL_API_KEYS를 쉼표로 구분된 목록(워크스페이스당 키 하나)으로 설정하면 모든 도구에 workspace 인수가 추가되어 어떤 워크스페이스에서 작업할지 지정합니다. 도구는 워크스페이스를 몇 개 구성하든 10개로 유지되며 워크스페이스별로 늘어나지 않습니다. 이는 각 도구 정의가 모델이 매 턴마다 비용을 지불하는 컨텍스트이기 때문에 중요합니다.

시작하기 전에 전용 읽기 전용 키를 발급하세요

이 서버에 AI 클라이언트를 연결하기 전에 Workel → 설정 → 개발자로 이동하여 이 목적을 위해 새 API 키를 발급하세요. 다른 통합이 이미 보유한 키를 재사용하지 마세요. 키 발급에는 소유자 또는 관리자 역할이 필요합니다. 이 릴리스의 도구가 실제로 사용하는 read:* 범위(read:projects, read:tasks, read:members, read:events — 아래 도구 참조)만 부여하고, 에이전트가 워크스페이스에서 스스로 생성하고 편집하도록 의도적으로 결정하지 않는 한 모든 write:* 범위는 선택하지 않은 상태로 두세요. 머신 또는 에이전트당 키 하나를 사용하고, 나중에 용도를 기억할 수 있도록 이름을 지정하세요. 머신이 폐기되거나 클라이언트가 손상된 경우 여러 도구가 공유하는 키를 교체하는 대신 해당 키 하나를 설정 → 개발자에서 해지하세요. 해지는 즉시 이루어지며 다음 요청에 적용됩니다.

아래 설명된 플래그를 다루기 전에 이해해야 할 두 가지가 있습니다:

• WORKEL_ENABLE_WRITES는 로컬 운영자 동의 플래그이지 인증 경계가 아닙니다. 이미 범위가 지정된 키에 제공되는 것을 좁힐 수만 있고 넓힐 수는 없습니다. 또한 구성 파일이나 환경 변수에 있으므로 AI 코딩 에이전트가 일반적으로 쓰기 액세스 권한을 가지므로, 머신에서 실행되는 에이전트가 스스로 true로 되돌릴 수 있습니다. 로컬 플래그는 신뢰할 수 없는 에이전트가 그대로 두도록 신뢰할 수 있는 것이 아닙니다. 키 자체의 범위(발급 시 의도적으로 부여하고 언제든지 해지할 수 있음)가 실제 게이트입니다.

• WORKEL_API_BASE_URL 재정의는 키를 다른 호스트로 보냅니다. 이 서버가 만드는 모든 요청은 Authorization 헤더에 키를 담습니다. WORKEL_API_BASE_URL이 제어하지 않는 URL을 가리키면 해당 호스트가 모든 호출에서 키를 받게 됩니다. 이 클라이언트는 정확히 이 이유로 localhost/127.0.0.1/[::1]을 제외한 일반 http:// 재정의를 거부합니다. 실제 키를 파일에 붙여넣는 경우에도 동일한 논리가 적용됩니다. git에 커밋된 적이 있다면 키를 교체하는 것이 유일한 실제 해결책입니다. git 기록은 영원합니다. 나중에 해당 줄을 삭제하는 커밋은 저장소 기록에서 제거하지 않으며, 그 사이에 저장소를 클론한 사람은 여전히 이전 키를 보유합니다.

설치

npx -y @workel/mcp@0.4.0

버전을 고정하세요. 위의 0.4.0은 이 패키지의 현재 릴리스입니다. 고정하기 전에 npm view @workel/mcp version으로 최신 버전을 확인하세요. 아래의 고정되지 않은 형식은 편의 전용으로, 일회성 수동 시도에는 적합하지만 에이전트 구성이 무인으로 실행하는 것에는 적합하지 않습니다:

npx -y @workel/mcp

환경 변수

doctor

MCP 클라이언트가 추가 세부 정보 없이 "서버 시작 실패"만 보고할 때마다 npx -y @workel/mcp@0.4.0 doctor를 실행하세요. 서버 자체가 실행하는 것과 정확히 동일한 시작 검사를 실행합니다 — 구성을 로드한 다음 GET /me를 프로브합니다 — 그리고 MCP 프로토콜을 말하려고 시도하는 대신 일반 텍스트 보고서를 stdout에 출력합니다:

base URL: https://api.workel.com/api/public/v1
workspace: Acme Inc
key: ci-key
scopes: read:projects, read:tasks
2 tools would register: workel_whoami, workel_list_projects
write budget: 59/60 remaining this minute

doctor는 전송을 시작하지 않으며 MCP 클라이언트와 통신하지 않습니다 — 터미널에서 실행하는 독립 실행형 명령이며, 성공 시 0으로, 실패 시(누락/잘못된 WORKEL_API_KEY, 연결할 수 없는 API, 또는 API가 거부하는 키) 1로 종료합니다. 서버가 일반 부팅 시 stderr에 출력하는 한 줄 요약(기본값일 때 기본 URL을 생략함)과 달리, doctor는 항상 실제 기본 URL을 출력합니다 — 기본값일 때도 포함합니다 — doctor 실행은 변조된 WORKEL_API_BASE_URL이 표시되어야 하는 바로 그 순간이기 때문입니다.

도구

이 릴리스는 다음 읽기 도구를 등록합니다. workel_whoami는 스코프가 전혀 필요 없으며 유효한 키로 작동합니다. 다른 모든 도구는 키의 스코프(위의 GET /me 프로브를 통해 발견됨)에 나열된 스코프가 포함된 경우에만 등록됩니다. 목록 도구는 호출당 기본적으로 25개의 결과를 반환하며(최대 50개 — 이 클라이언트는 API 자체의 100개보다 의도적으로 낮게 제한합니다. src/tools/conventions.ts 참조) 불투명한 cursor / next_cursor 쌍으로 페이지를 매깁니다.

쓰기 도구

4개이며, 두 게이트가 모두 통과할 때만 등록됩니다: 키가 일치하는 write:* 스코프를 보유하고 그리고 WORKEL_ENABLE_WRITES=true가 설정된 경우입니다. 둘 중 하나만으로는 아무것도 등록되지 않으므로, 읽기 전용 설치에서는 이 도구들이 전혀 표시되지 않습니다.

어떤 도구도 삭제를 수행하지 않습니다. workel_update_task는 destructiveHint: true로 주석 처리되어 있으므로, 주석을 존중하는 클라이언트는 호출할 때마다 확인을 요청합니다. 읽기 도구는 읽기 전용으로 주석 처리되어 있으며 확인 없이 실행됩니다.

mcp.workel.com의 호스팅 서버는 쓰기가 활성화된 상태로 실행되므로, 13개 도구 모두 해당 서버에서 사용할 수 있습니다.

제한 사항

replayed는 고유성을 증명하지 않습니다. 이 서버의 도구가 수행하는 모든 쓰기에는 Idempotency-Key가 포함되며, Workel API의 멱등성 저장소(24시간 보존, 호출 키 범위로 한정)는 동일한 키와 동일한 요청 본문으로 반복 시도할 때 정확히 동일한 응답을 재생합니다 — 두 번째 시도는 replayed: true를 보고하며, 두 번째로 생성되거나 변경되는 것은 없습니다.

replayed: false는 이 특정 시도가 실제로 실행되었음을 의미합니다 — 다른 곳에 중복이 없다는 것을 의미하지는 않습니다. 특히: 오류 응답은 절대 캐시되지 않으므로 실패 후 재시도는 항상 실제로 다시 실행됩니다. 멱등성 기록은 24시간 후 만료되므로 매우 늦은 재시도는 실제로 다시 실행됩니다. 그리고 저장소는 API 키별로 네임스페이스가 분리되므로, 다른 키로 전송된 동일한 리터럴 Idempotency-Key 값은 첫 번째 키가 생성한 중복과 충돌하지 않으며, 그 중복으로부터 보호하지도 않습니다. 도구 호출이 두 시도에서 동일한 멱등성 키를 명시적으로 재사용하지 않는 한, 각 시도는 서버가 판단할 수 있는 한 진정으로 독립적인 쓰기입니다.