Cherry Studio 설정 — API 키와 MCP 서버

Cherry Studio의 ‘설정’에서 많은 사람이 찾는 것은 두 가지입니다. 자신의 API 키로 모델을 사용하는 제공업체 설정과 외부 도구를 연결하는 MCP 서버 설정입니다. 전자는 설정 → 모델 제공업체 → 제공업체 추가에서, 후자는 설정 → MCP 서버에서 진행합니다. 이 페이지는 2026년 9월 30일 공개된 v2.1.4를 기준으로 화면의 일본어 표기를 그대로 사용해 두 절차를 설명합니다. v2에서 제공업체 추가 화면이 크게 변경되었으므로 v1 시대의 ‘유형: OpenAI’를 선택하라는 설명은 더 이상 화면과 일치하지 않습니다.

대상은 CherryHQ/cherry-studio의 데스크톱 버전(AGPL-3.0, Windows·macOS·Linux)입니다. 2026년 10월 1일 기준 저장소는 보관 처리되지 않았으며 최신 버전은 v2.1.4입니다. App Store에 있는 같은 이름의 앱은 다른 개발자가 만든 무관한 앱이므로 주의하세요. 화면을 일본어로 바꾸려면 설정의 언어에서 일본어를 선택합니다(UI는 일본어를 포함한 13개 언어를 지원합니다).

제공업체 설정: 내 API 키로 모델 사용하기

전체 절차입니다. 레이블은 v2.1.4 일본어 UI 표기입니다.

Cherry Studio v2.1.4

設定 → モデルプロバイダー → プロバイダーを追加
  （ダイアログ名：カスタムプロバイダーを追加）

  プロバイダー名            Kunavo
  APIキー                   sk-kn-...
  エンドポイント設定
    OpenAI                  https://api.kunavo.com/v1
    Anthropic メッセージ     https://api.kunavo.com
  その他のオプション
    OpenAI レスポンス        https://api.kunavo.com/v1   （任意）
    画像生成ベースURL         https://api.kunavo.com/v1   （任意）
    Google Gemini           空欄のまま

→ 保存 → モデル一覧で「モデルを同期」→ 使うモデルを追加 → 「チェック」

설정 → 모델 제공업체를 열고 제공업체 추가를 누릅니다. 열리는 대화상자의 제목은 ‘커스텀 제공업체 추가’입니다. Coding Plan 계열 서비스, 여러 계정, 프로젝트 분리 등으로 기존 제공업체를 기반으로 하고 싶다면 상단의 ‘프리셋에서 시작(선택 사항)’도 사용할 수 있습니다.
제공업체 이름과 API 키를 입력합니다.
엔드포인트 설정에는 처음부터 OpenAI와 Anthropic 메시지 두 필드가 있습니다. 텍스트용 엔드포인트가 최소 하나는 필수입니다. 둘 다 입력해 두면 채팅뿐 아니라 Agent 및 Anthropic 형식을 사용하는 기능에서도 모델을 선택할 수 있습니다.
기타 옵션을 열면 OpenAI 응답, Google Gemini, 이미지 생성 베이스 URL, 이미지 편집 베이스 URL 필드가 있습니다. 사용하지 않는 필드는 비워 두어도 됩니다.
저장한 후 제공업체 화면에서 활성 상태인지 확인합니다. 공식 문서에 따르면 설정되어 있어도 비활성 상태이면 모델이 선택지에 나타나지 않습니다. ‘키가 작동하지 않는다’는 문제의 가장 흔한 원인입니다.
모델 목록의 모델 동기화로 모델을 가져오고 사용할 모델을 추가한 뒤, 검사로 하나가 작동하는지 확인합니다.

주소 작성법: 루트만 입력하기

v2.1.4 소스에서는 각 필드에 입력한 루트 주소에 버전 부분이 없으면 /v1를 추가하고(이미 있으면 추가하지 않음), 이후 필드별 경로를 추가합니다. 각 필드 아래에 ‘요청 경로’로 최종 URL이 표시되므로 저장하기 전에 확인하면 확실합니다.

필드	Cherry Studio가 추가하는 경로	Kunavo
OpenAI	`/chat/completions`	지원
Anthropic 메시지	`/messages`	지원
OpenAI 응답(기타 옵션)	`/responses`	지원
이미지 생성 베이스 URL(기타 옵션)	`/images/generations`	지원
이미지 편집 베이스 URL(기타 옵션)	`/images/edits`	지원
Google Gemini(기타 옵션)	`/models/{model}:generateContent`	지원되지 않음 — 비워 둠

하지 말아야 할 것은 두 가지입니다. /chat/completions 또는 /messages까지 포함한 전체 URL을 붙여넣으면 경로가 중복되어 404가 발생합니다. 끝의 #는 화면의 도움말에 있는 대로 ‘자동으로 추가되는 API 버전을 비활성화’하는 기호이며, 표준 엔드포인트에 붙이면 /v1가 누락됩니다.

요금을 낭비하지 않는 기본 모델 설정

Cherry Studio는 채팅 외에도 백그라운드에서 모델을 호출합니다. 고속 모델은 화면 설명대로 ‘주제 이름 지정이나 검색 키워드 추출과 같은 간단한 작업’에 사용되며, 도움말에도 ‘경량 모델을 선택하고 추론 모델은 피하세요’라고 되어 있습니다. 여기에 저렴한 모델을 설정해 두면 대화할 때마다 비싼 모델이 실행되는 것을 막을 수 있습니다. 번역 모델도 별도로 설정할 수 있습니다. 여러 모델을 선택해 동시에 질문하면 모델 수만큼 별도의 요청(=별도의 청구)이 발생한다는 점도 기억하세요. 앱 내 사용량 통계의 금액은 공개 가격을 기준으로 한 추정치이므로 할인이 적용되는 경로에서는 실제보다 높게 표시됩니다. 모델 설정에서 단가를 자신의 요금으로 바꾸면 일치합니다. 자세한 내용은 영문판 Cherry Studio API cost를 참고하세요.

MCP 서버 설정: 외부 도구 연결하기

MCP는 모델(Agent)이 외부 도구나 데이터를 사용하도록 연결하는 방식입니다. 공식 문서의 절차는 설정 → MCP → MCP 서버 → 추가입니다. 추가 화면의 ‘빠른 생성’에서 연결 정보만 입력하면 서버를 만들 수 있고 나머지는 나중에 조정할 수 있습니다.

유형(화면 표기)	사용 상황	입력할 항목
표준 입력/출력 (stdio)	로컬 명령으로 실행되는 서버	명령, 인수, 환경 변수
서버 전송 이벤트 (sse)	SSE URL을 제공하는 원격 서비스	URL(필요한 경우 인증)
스트리밍 가능한 HTTP	Streamable HTTP URL을 제공하는 원격 서비스	URL(필요한 경우 인증)

MCP 서버 예시(로컬)

種類      標準入力/出力 (stdio)
コマンド   npx
引数       -y @modelcontextprotocol/server-filesystem /Users/you/notes
環境変数   （サーバーが求めるものだけ）

제공업체가 안내하는 연결 방식에 맞춰 유형을 선택합니다. 문서에서도 ‘이름으로 추측하지 말고 제공업체의 설정대로 입력’하도록 요구합니다.
저장하고 서버를 활성화한 뒤 상태가 정상이 될 때까지 기다립니다. 상세 화면의 ‘도구’, ‘프롬프트’, ‘리소스’ 탭에서 무엇이 제공되는지 확인합니다.
작업 → Agent 메뉴 → 편집 → MCP에서 해당 서버를 활성화합니다. 서버가 모든 Agent에 자동으로 연결되는 것은 아닙니다.
입력 필드의 ‘+’에서 서버가 제공하는 MCP 프롬프트나 MCP 리소스를 삽입할 수도 있습니다.

MCP 도구를 실제로 호출하는 것은 모델이므로 도구 호출을 지원하는 모델을 선택하세요. 위의 제공업체 설정에서 추가한 Claude와 GPT 모델은 도구 호출을 지원합니다. 문서의 권장대로 처음에는 하나씩 활성화해 작동을 확인하고, 쓰기나 비용이 발생하는 도구는 승인을 요구하는 설정으로 유지하는 것이 안전합니다. MCP의 ‘내장 서버’나 ‘마켓플레이스’에서 설치하는 경우에도 명령과 환경 변수의 내용을 확인하세요.

Kunavo 사용 시 주의사항 및 결제

검증 범위. 이 설정은 Cherry Studio 소스와 공식 문서를 바탕으로 작성되었으며 Kunavo가 Cherry Studio를 실제로 자체 엔드포인트에 연결해 실행한 검증은 아닙니다. 현재 작동하는 경로는 유지한 채 시도하세요.
Kunavo의 경로는 채팅과 이미지만 지원합니다. 임베딩 모델은 없으므로 지식 베이스의 벡터 검색에는 다른 제공업체나 로컬 임베딩 모델이 필요합니다(임베딩 없이도 BM25 키워드 검색으로 작동한다고 문서에 설명되어 있습니다).
결제. 선불 충전 방식이며 월정액은 없고 token 단위로 잔액에서 차감됩니다. 최소 충전 금액은 $10이며, Stripe Checkout에서 카드(Visa, Mastercard, American Express, JCB), Apple Pay, Google Pay 및 Link를 사용할 수 있습니다. 청구 안내를 확인하고 계정을 생성하여 키를 발급하세요. 영어 설정 페이지는 Cherry Studio integration guide입니다.

자주 묻는 질문

Cherry Studio에서 내 API 키를 설정하려면 어떻게 해야 하나요?

설정 → 모델 제공업체 → 제공업체 추가에서 ‘커스텀 제공업체 추가’ 대화상자를 열고, 제공업체 이름과 API 키를 입력한 뒤 엔드포인트 설정의 OpenAI 및 Anthropic 메시지 필드에 루트 주소를 입력하고 저장합니다. 이어서 모델 목록의 ‘모델 동기화’로 모델을 가져오고 사용할 모델을 추가한 다음 ‘검사’로 하나를 확인합니다. 제공업체를 활성화하지 않으면 모델 선택 화면에 나타나지 않는 점에도 유의하세요.

Cherry Studio API 주소에 /v1이 필요한가요?

둘 다 가능합니다. v2.1.4 소스에서는 입력한 루트 주소에 버전 부분(/v1)이 없으면 자동으로 추가하고, 이미 있으면 그대로 사용합니다. 이후 필드별 경로(OpenAI는 /chat/completions, Anthropic은 /messages)를 추가합니다. 피해야 할 것은 /chat/completions까지 포함한 전체 URL을 붙여넣는 것입니다. 경로가 중복되어 404가 발생합니다. 끝의 #은 버전 자동 추가를 중지하는 기호이므로 표준 엔드포인트에는 붙이지 마세요. 각 필드 아래 표시되는 ‘요청 경로’에서 최종 URL을 확인할 수 있습니다.

Cherry Studio의 MCP 서버는 어디에서 설정하나요?

공식 문서의 절차는 설정 → MCP → MCP 서버 → 추가입니다. 로컬 명령은 표준 입력/출력(stdio)을, 원격 서비스는 SSE 또는 Streamable HTTP를 사용하는 것이 일반적이며 제공업체의 설정에 맞춰 입력합니다. 저장 후 서버를 활성화하고, 상세 화면의 ‘도구’ 탭에서 제공되는 도구를 확인한 뒤 작업 → Agent 메뉴 → 편집 → MCP에서 해당 서버를 활성화합니다. 도구를 호출하는 것은 모델이므로 도구 호출을 지원하는 모델을 선택하세요.

Cherry Studio는 무료인가요?

데스크톱 버전(커뮤니티 버전)은 AGPL-3.0 오픈 소스이며 무료입니다. 비용이 발생하는 것은 설정한 제공업체의 모델 이용료입니다. Cherry Studio Enterprise는 견적제인 별도 제품이며, 내장된 CherryAI는 무료지만 모델 구성과 한도는 공개되지 않았습니다.

‘모델 동기화’에서 아무것도 나타나지 않으면 어떻게 하나요?

이 버튼은 입력한 주소와 키로 제공업체의 모델 목록(/v1/models)을 가져오므로 비어 있다면 먼저 주소나 키를 의심하세요. 전체 URL을 붙여넣지 않았는지, 끝에 #을 붙이지 않았는지 확인하고 같은 조합을 curl로 테스트하세요. JSON이 반환되면 앱 측 문제이고, 401이면 키 문제입니다.

2026년 10월 1일 확인: GitHub API(CherryHQ/cherry-studio, v2.1.4), v2.1.4 일본어 UI 문자열(ja-jp.json) 및 제공업체 추가 화면 소스, Cherry Studio 공식 문서의 MCP 페이지. Kunavo는 Cherry Studio를 자체 엔드포인트에서 실행하지 않았습니다.

Cherry Studio 설정 방법: API 프로바이더와 MCP 서버