mcp-linear

Linear 이슈 작업을 노출하는 MCP 서버. 독립형 — 내장된 Claude Linear MCP에 의존하지 않습니다.

이슈는 사람이 읽을 수 있는 식별자(GOV-123)로 주소가 지정됩니다. 상태, 팀, 라벨, 담당자는 이름으로 지정되며, 서버가 이를 Linear UUID로 변환하고 이름이 일치하지 않으면 유효한 옵션을 나열하는 오류를 반환합니다.

도구

설정

python3 -m venv .venv
.venv/bin/pip install -e ".[dev]"
cp .env.example .env
# Edit .env — set LINEAR_API_KEY

API 키 받기: Linear → 설정 → 보안 및 액세스 → 개인 API 키. 쓰기 작업에는 쓰기 액세스 권한이 있는 키가 필요합니다.

Claude Code에 추가

{
  "mcpServers": {
    "linear": {
      "command": "/Users/piuschungath/Workspace/mcp-linear/.venv/bin/mcp-linear",
      "env": { "LINEAR_API_KEY": "lin_api_..." }
    }
  }
}

테스트

.venv/bin/pytest

모든 HTTP는 respx로 모킹됩니다. API 키나 네트워크 액세스가 필요 없습니다.

mcp-pr-assistant와 함께 사용

두 서버는 서로를 임포트하지 않고도 구성됩니다: get_issue로 티켓을 가져오고, 해당 필드를 create_pr_from_ticket에 전달한 다음, add_comment로 PR URL을 다시 게시합니다.

스키마 검증

src/mcp_linear/queries.py의 GraphQL 필드 이름은 2026-08-21에 실제 Linear API에 대해 검증되었으며, 도구의 실제 쿼리 문자열(복사본이 아닌)을 실제 워크스페이스에 대해 실행하여 확인했습니다.

검증 완료:

• Float! 이슈 번호 비교자

• team { labels }를 통한 팀 범위 라벨

• 루트 issueLabels 연결

• viewer.assignedIssues(orderBy: updatedAt)

• 세 가지 변형이 전송하는 모든 필드 — IssueCreateInput, IssueUpdateInput 및 CommentCreateInput 모두 사용된 대로 teamId, title, description, stateId, assigneeId, priority, labelIds, issueId 및 body를 수용합니다.

하나의 차이가 발견되어 수정되었습니다:

• 전체 텍스트 검색. issueSearch는 query 인수를 더 이상 사용되지 않는 것으로 거부합니다. 검색은 이제 searchIssues(term: ...)를 사용하며, 이는 노드가 IssueSearchResult인 IssueSearchPayload를 반환합니다 — Issue가 아닙니다 — 따라서 IssueFields 프래그먼트를 확산할 수 없습니다. queries.py는 해당 유형에 대해 동일한 선택을 가진 두 번째 프래그먼트 SearchFields를 선언합니다. 인트로스펙션은 IssueSearchResult가 IssueFields가 선택하는 모든 필드를 보유함을 확인했습니다. 한 프래그먼트를 변경하면 다른 프래그먼트도 변경하세요.

한 가지는 아직 확인되지 않았습니다:

• 워크스페이스 라벨. 루트 issueLabels 연결은 해석되지만, 워크스페이스 전체 라벨만 반환하는지 — 아니면 다른 팀에 속한 팀 범위 라벨도 반환하는지 — 는 확인되지 않았습니다. 라벨 해석은 팀 자체 라벨을 먼저 참조하므로 팀 라벨이 항상 같은 이름의 워크스페이스 라벨보다 우선합니다.

Linear 스키마 변경 후 재검증하려면:

LINEAR_API_KEY=lin_api_... .venv/bin/python scripts/probe_schema.py <team-key> <issue-number> <issue-uuid>

팀 키, 해당 팀의 기존 이슈 번호, 해당 이슈의 UUID가 필요합니다(첫 번째 프로브에서 출력된 팀 UUID에 대해 한 번 대화형으로 프롬프트). 프로브는 읽기 전용입니다: 변형은 입력 유형을 인트로스펙션하여 확인되며, 트래커에 쓰지 않습니다.

참고 사항

• Linear 개인 API 키는 Bearer 접두사 없이 Authorization: <key>로 전송됩니다.

• Linear는 대부분의 실패를 최상위 errors 배열이 있는 HTTP 200으로 보고하므로, 클라이언트는 상태 코드가 아닌 응답 본문을 확인합니다.

• 팀, 상태, 라벨 및 사용자 메타데이터는 서버 프로세스 수명 동안 캐시됩니다. 팀의 워크플로 상태나 라벨을 변경한 후에는 서버를 다시 시작하세요.