Como configurar o Cherry Studio: provedor de API e servidor MCP

Nas “Configurações” do Cherry Studio, muitas pessoas procuram duas coisas. A configuração do provedor para usar modelos com sua própria chave de API e a configuração do servidor MCP para conectar ferramentas externas. A primeira fica em Configurações → Provedores de modelos → Adicionar provedor; a segunda, em Configurações → Servidores MCP. Esta página explica os dois procedimentos com os textos da interface em japonês exatamente como aparecem, com base na v2.1.4 publicada em 30 de setembro de 2026. Como a tela de adição de provedores mudou bastante na v2, guias da época da v1 que dizem para escolher “Tipo: OpenAI” já não correspondem à interface.

O escopo é a versão para desktop do CherryHQ/cherry-studio (AGPL-3.0, Windows, macOS e Linux). Em 1º de outubro de 2026, o repositório não estava arquivado e a versão mais recente era a v2.1.4. O aplicativo homônimo da App Store é de outro desenvolvedor e não tem relação com este projeto. Para mudar a interface para japonês, selecione japonês no idioma das configurações (a interface oferece 13 idiomas, incluindo japonês).

Configuração do provedor: usar modelos com sua própria chave de API

Esta é a visão geral do procedimento. Os rótulos são os da interface em japonês da 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           空欄のまま

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

1. Abra Configurações → Provedores de modelos e clique em Adicionar provedor. A caixa de diálogo aberta tem o título “Adicionar provedor personalizado”. Se quiser começar com base em um provedor existente, por exemplo para serviços de Coding Plan, várias contas ou separação de projetos, também pode usar “Começar a partir de uma predefinição (opcional)” na parte superior.
2. Informe o Nome do provedor e a Chave de API.
3. Em Configurações do endpoint, já aparecem os dois campos OpenAI e Mensagens Anthropic. Pelo menos um endpoint de texto é obrigatório. Preencher ambos permite selecionar modelos não apenas no chat, mas também no Agent e em recursos que usam o formato Anthropic.
4. Ao abrir Outras opções, aparecem campos para Respostas OpenAI, Google Gemini, URL base de geração de imagens e URL base de edição de imagens. Os campos que você não usar podem permanecer vazios.
5. Depois de salvar, confirme na tela do provedor se ele está Ativado. Segundo a documentação oficial, mesmo configurado, um provedor desativado não aparece entre as opções de modelos. Essa é a causa mais comum de a “chave não funcionar”.
6. Use Sincronizar modelos na lista de modelos para importá-los, adicione os que deseja usar e confirme o funcionamento de um modelo com Verificar.

Como escrever o endereço: informe apenas a raiz

No código-fonte da v2.1.4, se o endereço raiz inserido em cada campo não tiver a parte de versão, /v1 será adicionada (e não será adicionada se já existir); depois, o caminho específico do campo será acrescentado. A URL final aparece abaixo de cada campo como “Caminho da solicitação”, portanto basta conferi-la antes de salvar.

Há duas coisas que você não deve fazer. /chat/completions e /messages: se você colar uma URL completa que já os inclua, o caminho ficará duplicado e causará 404. O # no final é o símbolo que, como indica a dica da interface, “desativa a versão da API adicionada automaticamente”; ao colocá-lo em um endpoint padrão, /v1 ficará ausente.

Configurar o modelo padrão para evitar desperdício

O Cherry Studio chama modelos em segundo plano também fora do chat. O modelo rápido é usado, conforme a descrição da tela, para “tarefas simples, como nomear tópicos e extrair palavras-chave de pesquisa”; a dica também diz “selecione um modelo leve e evite modelos de raciocínio”. Basta colocar aqui um modelo barato para evitar que um modelo caro seja executado a cada conversa. O modelo de tradução também pode ser configurado separadamente. Lembre-se de que fazer uma pergunta simultaneamente a vários modelos gera uma solicitação separada para cada modelo (= cobranças separadas). Os valores nas estatísticas de uso do aplicativo são uma estimativa baseada nos preços públicos e ficam acima do real em rotas com desconto. Atualize o preço unitário nas configurações do modelo com suas próprias tarifas para ajustar o valor. Para mais detalhes, consulte a versão em inglês de Cherry Studio API cost.

Configuração do servidor MCP: conectar ferramentas externas

MCP é um método de conexão que permite ao modelo (Agent) usar ferramentas e dados externos. O procedimento da documentação oficial é Configurações → MCP → Servidores MCP → Adicionar. Na tela de adição, basta inserir as informações de conexão em “Criação rápida” para criar o servidor; o restante pode ser ajustado depois.

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

1. Escolha o tipo conforme o método de conexão indicado pelo provedor. A documentação também pede que você “não deduza pelo nome e insira exatamente conforme as configurações do provedor”.
2. Salve e ative o servidor; aguarde até que o estado fique normal. Nas abas “Ferramentas”, “Prompts” e “Recursos” dos detalhes, confira o que é fornecido.
3. Em Trabalho → menu do Agent → Editar → MCP, ative esse servidor. Os servidores não são adicionados automaticamente a todos os Agents.
4. No campo de entrada, pelo “+”, você também pode inserir prompts MCP ou recursos MCP fornecidos pelo servidor.

Quem efetivamente chama as ferramentas MCP é o modelo, portanto escolha um modelo compatível com chamadas de ferramentas. Os modelos Claude e GPT adicionados na configuração do provedor acima são compatíveis com chamadas de ferramentas. Conforme recomendado pela documentação, no início ative um de cada vez e verifique o funcionamento; mantenha configurada a exigência de aprovação para ferramentas que fazem gravações ou geram cobranças. Mesmo ao instalar servidores em “Servidores integrados” ou no “Marketplace” do MCP, confira o conteúdo dos comandos e das variáveis de ambiente.

Observações e pagamento ao usar o Kunavo

• Escopo da verificação. Esta configuração foi criada com base no código-fonte e na documentação oficial do Cherry Studio; não foi verificada executando o Cherry Studio com o endpoint próprio do Kunavo. Teste mantendo intacta a rota que está funcionando atualmente.
• A rota do Kunavo é apenas para chat e imagens. Como não há modelos de embeddings, a busca vetorial da base de conhecimento exige outro provedor ou um modelo de embeddings local (a documentação explica que também é possível funcionar com busca por palavras-chave BM25 sem embeddings).
• Pagamento. Recarga pré-paga sem mensalidade; o saldo é descontado por token. A recarga mínima é de $10. No checkout da Stripe, você pode usar cartões (Visa, Mastercard, American Express, JCB), Apple Pay, Google Pay e Link. Consulte as informações de cobrança, crie uma conta e emita sua chave. A página de configuração em inglês é o guia de integração do Cherry Studio.

Perguntas frequentes

Verificado em 1º de outubro de 2026: API do GitHub (CherryHQ/cherry-studio, v2.1.4), strings da interface em japonês da v2.1.4 (ja-jp.json), código-fonte da tela de adição de provedores e página MCP da documentação oficial do Cherry Studio. O Kunavo não executou o Cherry Studio contra seu próprio endpoint.