# Claude Code에 Storelift MCP 서버 추가하기

URL: https://storelift.net/ko/guide/storelift-mcp-claude-code/
Language: ko
Updated: 2026-10-13

Storelift MCP 서버를 Claude Code에 연결하는 단계입니다. 버전, 요구 사항, 오류 응답은 서버에서 직접 측정했습니다.

## 이 가이드를 확인한 방법

NOTE: 확인한 방법(2026-10-11). 서버 쪽은 storelift-mcp 1.1.1에서 핸드셰이크, 도구 목록, 읽기 호출, 오류 응답, 접근 권한 제거를 측정했습니다. Claude Code에서 확인한 것: 2.1.296 · stdio, API 키: 연결됨, 도구 8개 나열, 제거 명령으로 깔끔하게 제거됨; 2.1.296 · Streamable HTTP, 헤더의 API 키: 연결됨, 도구 8개 나열. Claude Code 안에서의 도구 호출은 아직 시도하지 않았으며, 아래 단계는 Claude Code 자체 문서를 따릅니다.

Claude Code 문서: code.claude.com.

## 버전

이 가이드는 현재 운영 중인 서버를 설명합니다. npm의 storelift-mcp 1.1.1(2026-09-14), 그리고 호스팅 엔드포인트 https://storelift.net/mcp입니다. 둘 다 같은 도구 8개를 제공합니다: get_ai_visibility, get_charts, get_history, get_keywords, get_reviews, get_rivals, get_store_page, list_apps.

이 릴리스의 도구는 모두 읽기 도구이며, 계정의 어떤 것도 변경하지 않습니다. 프로토콜 버전은 로컬 서버(stdio)가 2024-11-05, 호스팅 엔드포인트(Streamable HTTP)가 2025-06-18입니다. 엔드포인트는 상태를 저장하지 않으며, 세션 ID도 서버가 보내는 스트림도 없습니다.

## 요구 사항

- 플랜. MCP 접근에는 Pro, Studio 또는 Enterprise 플랜이 필요합니다. API 키를 쓰든 로그인(OAuth)을 쓰든 같습니다.
- 키. Storelift → 설정 → API 키. 키는 sl_live_로 시작합니다. 이 릴리스의 키에는 스코프가 없습니다. 키 하나가 워크스페이스의 모든 앱을 읽습니다. 키는 클라이언트 설정에만 보관하세요.
- 실행 환경. 로컬 서버에는 Node.js 18 이상이 필요합니다(npx가 첫 실행 때 패키지를 내려받습니다). 호스팅 엔드포인트는 설치할 것이 없습니다.
- Claude Code. 최신 버전이면 됩니다. 아래 명령은 claude mcp add --help와 Claude Code의 MCP 문서에서 가져왔습니다.

## 설정 방법

API 키를 쓰는 로컬 서버입니다(프로젝트 디렉터리에서 실행하세요. 기본 범위는 이 프로젝트뿐입니다):

claude mcp add storelift -e STORELIFT_API_KEY=sl_live_... -- npx -y storelift-mcp

또는 설치할 것이 없는 호스팅 엔드포인트입니다. 키는 헤더에 넣습니다:

claude mcp add --transport http storelift https://storelift.net/mcp --header "Authorization: Bearer sl_live_..."

키 대신 로그인(OAuth)을 쓰려면 헤더 없이 엔드포인트를 추가한 뒤 Claude Code 안에서 /mcp를 실행하세요:

claude mcp add --transport http storelift https://storelift.net/mcp

claude mcp list로 연결을 확인하세요. 해당 줄에 ✔ Connected가 보여야 합니다.

## 첫 조회

이렇게 물어보세요: “내 Storelift 앱 목록을 보여 주고, 첫 번째 앱의 미국 키워드 순위를 알려 줘.” 어시스턴트는 먼저 list_apps를 호출하고, 이어서 내가 고른 앱에 대해 get_keywords를 호출합니다. list_apps 응답은 다음과 같습니다(Storelift 샘플 데이터, 2026-09-28. 내 계정에서는 내 앱이 반환됩니다):

{
"apps": [
{
"id": "sbx-lumen",
"name": "Lumen — Sleep Sounds",
"countries": [
"us",
"gb",
"de"
],
"keywords": [
"sleep sounds",
"white noise",
"rain sounds"
]
}
]
}

get_keywords는 추적 중인 키워드마다 한 행을 반환합니다:

{
"country": "us",
"platform": "ios",
"keywords": [
{
"term": "sleep sounds",
"measured": true,
"rank": null,
"demand": 73,
"searchDepth": 200
},
{
"term": "white noise",
"measured": true,
"rank": 57,
"demand": 37,
"searchDepth": 200
}
]
}

rank에 숫자가 있으면 그 값이 순위입니다. null은 키워드를 측정했지만 앱이 결과에 없다는 뜻이고, measured: false는 측정하지 못했다는 뜻입니다. 이 셋은 구분해서 다뤄야 합니다. 측정되지 않은 날을 0으로 세면 틀린 답이 나옵니다.

연결이 작동합니다. 다음은 첫 작업 세 가지입니다. 어떤 키워드가 떨어졌는지, 그 키워드에서 누가 앞서 있는지, 오늘 측정이 없는 키워드는 어떻게 답해야 하는지를 기대되는 답과 함께 다룹니다.

## 접근 권한 제거

1. claude mcp remove storelift를 실행하세요. 로그인으로 연결한 경우 Claude Code가 저장해 둔 토큰도 함께 삭제합니다. /mcp → Clear authentication은 서버를 제거하지 않고 같은 일을 합니다.
2. Storelift → 설정 → API 키에서 키를 삭제하세요. 그 키로 보내는 다음 요청부터 거부됩니다(로컬 서버에서는 도구 오류, 호스팅 엔드포인트에서는 HTTP 401). 끝나기를 기다려야 하는 열린 세션은 없습니다.
3. 로그인(OAuth)으로 연결했다면 설정 → API → 연결된 앱에서 연결을 제거하세요. 그 연결의 토큰은 다음 요청에서 401을 받습니다.

## 문제 해결

| 증상 | 원인 | 해결 방법 |
| --- | --- | --- |
| “No API key was sent…” | 로컬 서버가 키 없이 시작됐습니다. 도구 목록은 나오지만 모든 호출이 이 메시지를 반환합니다. | 서버 설정에 STORELIFT_API_KEY를 추가하고 클라이언트를 다시 시작하세요. |
| “This API key is not valid…” | 키를 잘못 입력했거나 키가 삭제됐습니다. 호스팅 엔드포인트는 HTTP 401로 응답합니다. | 설정 → API 키에서 새 키를 만들고, 클라이언트 설정에 넣어 둔 키를 새 키로 바꾸세요. |
| “The Public API is available on the Pro and Studio plans…” | 계정의 플랜으로는 MCP 접근이 열리지 않습니다(HTTP 403). 이 릴리스에서는 Pro, Studio 또는 Enterprise 플랜에서 접근할 수 있습니다. | storelift.net/pricing에서 업그레이드하세요. 키는 그대로 유지되며, 플랜이 허용하면 다시 작동합니다. |
| “fetch failed…” | 로컬 서버가 Storelift에 연결하지 못했습니다. 네트워크, 프록시 또는 방화벽 문제입니다. | 이 컴퓨터에서 https://storelift.net에 접속되는지 확인하세요. STORELIFT_API는 다른 엔드포인트를 안내받은 경우에만 설정하세요. |
| claude mcp list에 ✘ Failed to connect가 표시됨 | 서버가 시작되지 않았거나(Node.js가 없거나 너무 오래된 버전) 엔드포인트가 제때 응답하지 않았습니다. | node --version을 실행해 보세요. 시작이 느리다면 시작 제한 시간을 늘리세요. 예: MCP_TIMEOUT=10000 claude. |