Linear MCP 서버

Linear MCP 서버

LiteLLM MCP 게이트웨이를 통해 Linear의 호스팅 원격 MCP 서버를 연결해 이슈·프로젝트·사이클·댓글을 다뤄 보세요.

Linear가 서버를 중앙에서 호스팅·관리하므로 직접 배포하거나 실행할 것이 없어요. LiteLLM은 키·팀별 접근 제어, 도구 호출별 비용 추적, 노출한 모든 MCP 서버에 걸친 단일 감사 추적과 함께 중앙 집중식 인증을 추가해요.

출처: 문서

본문

이 서버를 언제 사용하나요 (When should you use this server)

  • 에이전트가 작업이 논의되는 곳 어디서든 이슈를 작성·분류·업데이트하게 하기
  • 계획이나 추정 전에 현재 사이클·프로젝트 상태를 컨텍스트로 가져오기
  • 코딩 에이전트에게 구현 중인 티켓을 주고 진행 상황을 댓글로 달게 하기

주요 기능 (Key features)

  • 전용 읽기 전용 엔드포인트가 있어 작성·편집 권한을 부여하지 않고 Linear 컨텍스트를 제공할 수 있어요
  • Streamable HTTP로 Linear가 호스팅. 기존 SSE 엔드포인트는 더 이상 사용하지 않는 폴백으로만 남아 있음
  • OAuth용 동적 클라이언트 등록과, 로그인할 사람이 없는 백엔드 에이전트용 API 키 경로를 제공

인증 (Authentication)

  • 방법: 사용자 토큰을 사용하는 OAuth 2.1. 각 호출자의 기존 Linear 권한을 존중해요. Linear는 동적 클라이언트 등록을 지원하므로 관리할 client ID나 secret이 없어요.
  • 대안: 베어러 토큰으로 보내는 Linear API 키. 이는 사용자별이 아닌 단일 공유 신원이므로, 읽기 전용 컨텍스트 소스와 무인 백엔드 에이전트에만 아껴 쓰세요.

엔드포인트 (Endpoint)

원격 MCP 서버:

https://mcp.linear.app/mcp

읽기 전용:

https://mcp.linear.app/mcp/readonly

Linear는 또한 Streamable HTTP를 지원하지 않는 클라이언트를 위한 더 이상 사용하지 않는 폴백으로 https://mcp.linear.app/sse를 노출해요. 새 구성에는 /mcp 엔드포인트를 사용하세요.

LiteLLM MCP 게이트웨이로 연결 (Connect via LiteLLM MCP Gateway)

클라이언트 자격 증명은 빼 두세요 — OAuth 서버에 client_id, client_secret, token_url을 설정하지 마세요. 그렇게 하면 모든 호출자가 공유하는 machine-to-machine 신원으로 전환되어 이슈가 요청한 사람이 아니라 하나의 서비스 계정으로 생성돼요. Linear의 동적 등록 덕분에 불필요해요. 공유 신원이 실제로 필요하다면 아래 API 키 탭을 사용하세요. 명시적이에요.

1단계: LiteLLM에 서버 등록 (Register the server in LiteLLM)

LiteLLM UI:

MCP Servers로 이동해 + Add New MCP Server 클릭 후 설정:

필드 값
Server Name linear_mcp
Transport HTTP
Server URL https://mcp.linear.app/mcp
Authentication OAuth
OAuth flow type Interactive (PKCE)
Client ID / Client Secret 비워 둠

Create MCP Server 클릭 후 서버의 MCP Tools 탭을 열어 연결을 확인하세요. 첫 목록화에서 Linear 로그인을 거치게 돼요.

config.yaml:

mcp_servers:
  linear_mcp:
    url: "https://mcp.linear.app/mcp"
    transport: "http"
    description: "Linear issues, projects, and cycles"
    auth_type: oauth2
    oauth2_flow: authorization_code

oauth2_flow: authorization_code는 대화형 사용자별 흐름을 선택하며 필수예요. 이를 생략한 auth_type: oauth2 서버에서는 프록시가 시작을 거부해요. MCP 서버 저장에는 store_model_in_db: true도 필요해요.

공유 읽기 전용 컨텍스트 소스 또는 브라우저 로그인을 완료할 사람이 없는 백엔드 에이전트를 위해 Linear API 키로 인증할 수도 있어요. Linear에서 Settings > Security & access > Personal API keys 아래 Read 권한만 활성화한 상태로 생성하고, 읽기 전용 엔드포인트와 짝지으세요:

config.yaml (API 키):

mcp_servers:
  linear_readonly:
    url: "https://mcp.linear.app/mcp/readonly"
    transport: "http"
    description: "Linear, read-only"
    auth_type: bearer_token
    auth_value: os.environ/LINEAR_API_KEY

모든 호출자가 이 신원을 공유하므로 도구 호출이 최종 사용자가 아니라 키 소유자에게 귀속돼요. 사용자 대면이거나 쓰기가 필요한 것은 OAuth를 선호하세요.

2단계: 프록시의 공용 origin 설정 (Set the proxy's public origin)

LiteLLM이 TLS 종료 인그레스 뒤에서 실행된다면 PROXY_BASE_URL을 사용자가 주소창에서 보는 origin으로 설정해 OAuth 콜백이 검증되도록 해 주세요:

PROXY_BASE_URL=https://llm.example.com

불일치는 Connect 클릭 시 400 Bad Request와 {"detail":"invalid_request"}로 나타나요. 전체 규칙은 Reverse proxy and ingress configuration에 있어요.

3단계: 에이전트에서 연결 (Connect from an agent)

게이트웨이는 각 서버를 http://localhost:4000/{server_name}/mcp로 제공하므로 linear_mcp는 http://localhost:4000/linear_mcp/mcp에서 접근 가능해요.

Claude Desktop / Cursor:

{
  "mcpServers": {
    "linear": {
      "url": "http://localhost:4000/linear_mcp/mcp",
      "headers": {
        "x-litellm-api-key": "Bearer sk-<your-litellm-api-key>"
      }
    }
  }
}

Claude Code:

claude mcp add --transport http linear http://localhost:4000/linear_mcp/mcp \
  --header "x-litellm-api-key: *** $LITELLM_API_KEY"

첫 호출에서 Linear 로그인용 브라우저가 열려요. LiteLLM이 그 사용자의 토큰을 저장하고 이후 새로고침하므로 이후 세션은 프롬프트 없이 연결돼요.

제공 도구 (Tools provided)

info — Linear는 도구 정의를 런타임에 tools/list로 게시하므로 이름과 필드가 고지 없이 바뀔 수 있어요. LiteLLM UI의 MCP Tools 탭이 워크스페이스가 노출하는 것의 진실이며, 라이브 도구를 나열하고 테스트 인자로 하나를 호출할 수 있게 해줘요. 업스트림 세부 사항은 Linear의 MCP 문서를 참고해 주세요.

영역 도구
이슈(Issues) get_issue, list_issues, create_issue, update_issue, list_my_issues
이슈 메타데이터 list_issue_statuses, get_issue_status, list_issue_labels
프로젝트(Projects) list_projects, get_project, create_project, update_project
댓글(Comments) list_comments, create_comment
문서(Documents) get_document, list_documents
사이클(Cycles) list_cycles
팀(Teams) list_teams

쓰기는 이슈·프로젝트·댓글로 제한되며 문서, 사이클, 팀, 상태, 라벨은 읽기 전용이에요. LiteLLM은 도구 이름에 서버 이름을 접두사로 붙이므로 create_issue는 모델에 linear_mcp-create_issue로 노출돼요(Tool naming 참고).

쓰기 없는 읽기 (Reads without writes)

읽기 전용 엔드포인트가 읽기만 부여하는 가장 깔끔한 방법이자 기본으로 선택할 방법이에요. 표준 엔드포인트에서는 동의 시점에 쓰기 스코프를 거부하거나 config에서 쓰기 도구를 제외해 같은 결과를 얻을 수 있어요. disallowed_tools 항목이 더 이상 실제 도구와 일치하지 않으면 조용히 실패해 그 도구가 호출 가능한 채로 남으므로, 먼저 라이브 도구 목록에 이름을 확인하세요:

config.yaml:

mcp_servers:
  linear_mcp:
    url: "https://mcp.linear.app/mcp"
    transport: "http"
    auth_type: oauth2
    oauth2_flow: authorization_code
    disallowed_tools: ["create_issue", "update_issue", "create_project", "update_project", "create_comment"]

사용자를 제한하세요 — object_permission으로 서버를 키·팀별로 부여하고 mcp_rpm_limit으로 서버별 호출량 상한을 두세요. 두 가지 모두 MCP Permission Management에서 다룹니다.

LiteLLM 키를 x-litellm-api-key에 넣으세요 — 대화형 OAuth는 업스트림 토큰을 위해 Authorization 헤더가 비어 있어야 해요. 클라이언트가 LiteLLM API 키를 Authorization: Bearer ***로 보내면 OAuth 흐름이 실행되지 않고 LiteLLM이 LiteLLM 키를 Linear에 전달하며 Linear가 거부해요. 진단하려면 x-litellm-mcp-debug: true를 추가하고 응답 헤더를 읽으세요. SAME_AS_LITELLM_KEY는 이 경우를 확인하고, m2m-client-credentials는 token_url`이 설정되어 모든 호출자가 하나의 신원을 공유함을 의미해요. Debugging OAuth와 MCP Troubleshooting Guide를 참고하세요.

인증된 세션은 하나의 Linear 워크스페이스에 묶이며, 재연결만으로는 전환되지 않아요. 두 번째 워크스페이스가 필요한 사용자는 별도 MCP 서버 항목으로 등록해야 해요.

더 알아보기 (Learn more)