Come configurare Cherry Studio: provider API e server MCP

Nelle «Impostazioni» di Cherry Studio, molte persone cercano due cose: la configurazione del provider per usare i modelli con la propria chiave API e la configurazione del server MCP per collegare strumenti esterni. La prima si apre da Impostazioni → Provider di modelli → Aggiungi provider, la seconda da Impostazioni → Server MCP.Questa pagina si basa sulla v2.1.4 pubblicata il 30 settembre 2026 e descrive entrambe le procedure mantenendo le etichette giapponesi dell'interfaccia. Poiché nella v2 la schermata di aggiunta del provider è cambiata molto, le guide dell'epoca v1 che indicano «Tipo: OpenAI» non corrispondono più all'interfaccia.

Questa guida riguarda la versione desktop di CherryHQ/cherry-studio (AGPL-3.0, Windows, macOS e Linux). Al 1° ottobre 2026 il repository non è archiviato e l'ultima versione è v2.1.4. L'app con lo stesso nome presente nell'App Store appartiene a uno sviluppatore diverso e non è correlata a questo progetto: fai attenzione. Per impostare l'interfaccia in giapponese, seleziona il giapponese nelle impostazioni della lingua (l'interfaccia supporta 13 lingue, incluso il giapponese).

Configurazione del provider: usare i modelli con la propria chiave API

Ecco la procedura completa. Le etichette corrispondono all'interfaccia giapponese della 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. Apri Impostazioni → Provider di modelli e premi Aggiungi provider. Il titolo della finestra è «Aggiungi provider personalizzato». Se vuoi partire da un provider esistente, ad esempio per servizi di tipo Coding Plan, più account o separazione dei progetti, puoi usare anche «Inizia da un preset (opzionale)» in alto.
2. Inserisci il nome del provider e la chiave API.
3. In Impostazioni degli endpoint sono già presenti due campi: OpenAI e Messaggi Anthropic. È obbligatorio configurare almeno un endpoint di testo. Compilandoli entrambi, puoi scegliere i modelli anche nelle funzioni che usano Agent o il formato Anthropic, oltre alla chat.
4. Aprendo Altre opzioni trovi i campi per le risposte OpenAI, Google Gemini, l'URL di base per la generazione delle immagini e l'URL di base per la modifica delle immagini. Puoi lasciare vuoti i campi che non utilizzi.
5. Dopo il salvataggio, verifica che il provider sia abilitato nella schermata del provider. Secondo la documentazione ufficiale, se rimane disabilitato i modelli configurati non compaiono tra le opzioni. È questa la causa più comune del problema «la chiave non funziona».
6. Usa Sincronizza modelli nell'elenco dei modelli per importarli, aggiungi quelli che vuoi usare e verifica il funzionamento di un modello con Controlla.

Come scrivere l'indirizzo: inserisci solo la radice

Nel codice sorgente di v2.1.4, se all'indirizzo radice inserito in un campo manca la parte relativa alla versione, viene aggiunto /v1 (se è già presente, non viene aggiunto); dopodiché viene aggiunto il percorso specifico del campo. Sotto ogni campo viene mostrato l'URL finale come «Percorso della richiesta», quindi controllalo prima del salvataggio per andare sul sicuro.

Ci sono due cose da non fare. Se incolli un URL completo che include anche /chat/completions o /messages, il percorso viene duplicato e restituisce 404. Il suffisso finale #, come indicato nel suggerimento dell'interfaccia, è il simbolo per «disabilitare la versione API aggiunta automaticamente»; se lo aggiungi a un endpoint standard, viene omesso /v1.

Configurare il modello predefinito per non sprecare denaro

Cherry Studio chiama modelli in background anche per funzioni diverse dalla chat. Il modello veloce viene usato, come spiega l'interfaccia, per «attività semplici come assegnare un nome agli argomenti o estrarre parole chiave per la ricerca»; il suggerimento raccomanda inoltre di «selezionare un modello leggero ed evitare i modelli di ragionamento». Impostando qui un modello economico eviti che a ogni conversazione venga utilizzato un modello costoso. Puoi configurare separatamente anche il modello di traduzione. Ricorda inoltre che, selezionando più modelli e ponendo loro la stessa domanda contemporaneamente, generi tante richieste separate quanti sono i modelli (quindi anche tante fatture separate). Gli importi nelle statistiche di utilizzo dell'app sono stime basate sui prezzi pubblici e, per i percorsi con sconti, risultano più alti del costo effettivo. Aggiorna il prezzo unitario nelle impostazioni del modello con la tua tariffa per ottenere valori corretti. Per maggiori dettagli, consulta la versione inglese di Cherry Studio API cost.

Configurazione dei server MCP: collegare strumenti esterni

MCP è un metodo di connessione che consente al modello (Agent) di utilizzare strumenti o dati esterni. La procedura nella documentazione ufficiale è Impostazioni → MCP → Server MCP → Aggiungi. Nella schermata di aggiunta puoi creare un server inserendo solo le informazioni di connessione tramite «Creazione rapida» e modificare il resto in seguito.

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

1. Scegli il tipo in base al metodo di connessione indicato dal fornitore. La documentazione richiede inoltre di «non dedurre il tipo dal nome, ma inserire i dati secondo la configurazione del fornitore».
2. Salva e abilita il server, quindi attendi che lo stato diventi normale. Nelle schede dettagliate «Strumenti», «Prompt» e «Risorse» verifica cosa viene fornito.
3. Vai su Lavoro → menu Agent → Modifica → MCP e abilita il server. I server non vengono aggiunti automaticamente a tutti gli Agent.
4. Dal pulsante «+» del campo di input puoi anche inserire i prompt MCP o le risorse MCP fornite dal server.

Poiché è il modello a chiamare effettivamente gli strumenti MCP, scegli un modello compatibile con le chiamate agli strumenti. I modelli Claude o GPT aggiunti nelle impostazioni del provider sopra riportate supportano le chiamate agli strumenti. Come raccomanda la documentazione, all'inizio abilita un solo strumento alla volta e verifica il funzionamento; per gli strumenti che eseguono scritture o addebiti, mantieni l'impostazione che richiede l'approvazione. Anche quando installi strumenti dai «Server integrati» o dal «Marketplace» MCP, controlla il contenuto dei comandi e delle variabili d'ambiente.

Note e pagamenti per l'utilizzo di Kunavo

• Ambito della verifica. Questa configurazione è stata preparata sulla base del codice sorgente e della documentazione ufficiale di Cherry Studio; non si tratta di una verifica in cui Kunavo ha collegato Cherry Studio ai propri endpoint e lo ha eseguito. Provala mantenendo intatto il percorso che stai utilizzando ora.
• Con Kunavo sono disponibili solo chat e immagini. Non sono disponibili modelli di embedding, quindi per la ricerca vettoriale nella knowledge base serve un altro provider o un modello di embedding locale (la documentazione spiega che, anche senza embedding, è possibile usare la ricerca per parole chiave BM25).
• Pagamento. Il sistema è prepagato, senza canone mensile: l’importo viene detratto dal saldo in base ai token. La ricarica minima è $10; al checkout Stripe puoi utilizzare carte (Visa, Mastercard, American Express, JCB), Apple Pay, Google Pay e Link. Consulta Spiegazione della fatturazione, quindi crea un account e genera una chiave. La pagina di configurazione in inglese è Cherry Studio integration guide.

Domande frequenti

Verificato il 1 ottobre 2026: API GitHub (CherryHQ/cherry-studio, v2.1.4), stringhe dell'interfaccia giapponese di v2.1.4 (ja-jp.json), sorgente della schermata di aggiunta dei provider e pagina MCP della documentazione ufficiale di Cherry Studio. Kunavo non ha eseguito Cherry Studio sui propri endpoint.