# Cherry Studio Setup Guide

URL: https://research-memex.org/docs/implementation/agentic-ai-tools/cherry-studio-setup-guide
Description: Cherry Studio is useful when a research workflow needs chat, files, models, and MCP servers in one interface.



<GuideMeta>
  Beginner · 20–30 min · API key required
</GuideMeta>

*Research starts with seeing. A unified GUI lets you explore before you commit to a terminal workflow.*

## Overview [#overview]

Cherry Studio brings chat, knowledge bases, MCP servers, and CLI coding agents into one GUI. It is the central interface for researchers who want model comparison and file-based work without starting in a terminal.

Features:

* Multiple AI model access through one interface (100+ models)
* Knowledge Base for loading your literature corpus
* MCP servers for Zotero, web search, and other external tools
* Code Tools for launching CLI agents such as Claude Code, Antigravity CLI, and OpenAI Codex from within Cherry Studio
* Conversation forking for exploring different analytical paths
* Export to markdown for Obsidian integration

Official documentation: [Cherry AI Docs](https://docs.cherry-ai.com/docs/en-us) and the [installation guide](https://docs.cherry-ai.com/docs/en-us/cherry-studio/installation/macos).

***

<Steps titleSize="h2">
  <Step title="Download and install Cherry Studio" stepNumber="1">
    Visit [Cherry Studio GitHub Releases](https://github.com/CherryHQ/cherry-studio/releases) and download the version for your operating system.

    <Tabs>
      <Tab title="macOS" icon="apple">
        1. Open the downloaded `.dmg` file
        2. Drag Cherry Studio to your Applications folder
        3. First launch: Right-click → Open (to bypass security warning)
      </Tab>

      <Tab title="Windows" icon="windows">
        1. Run the downloaded `.exe` file
        2. Follow the installation wizard
        3. Launch from Start Menu or Desktop shortcut
      </Tab>

      <Tab title="Linux" icon="linux">
        1. Make the AppImage executable: `chmod +x Cherry-Studio-*.AppImage`
        2. Double-click to run
      </Tab>
    </Tabs>
  </Step>

  <Step title="Initial configuration" stepNumber="2">
    When you first open Cherry Studio, you'll see:

    * Welcome screen with model selection
    * API configuration section
    * Settings panel

    Navigate to settings by clicking the **Settings** icon (gear icon) in the sidebar, then select **API Keys** or **Model Configuration**. For API-key basics, free tiers, provider options, and setup instructions, see the [API Keys Setup Guide](/docs/implementation/ai-environment-setup/api-keys-setup-guide).
  </Step>

  <Step title="Configure API provider" stepNumber="3">
    You'll need an API key from a provider to access AI models. See the [API Keys Setup Guide](/docs/implementation/ai-environment-setup/api-keys-setup-guide) for detailed instructions on getting keys from Google AI Studio (free), OpenRouter, or other providers. If you are following the Systematic Review course, use the shared OpenRouter key supplied by your instructor and skip the API setup guide.

    <Steps titleSize="h3">
      <Step title="Navigate to API settings" stepNumber="3.1">
        1. In Cherry Studio, click the **Settings** icon (gear icon)
        2. In the settings menu, select **API Keys**
      </Step>

      <Step title="Add your provider" stepNumber="3.2">
        1. In the API Keys panel, click the **Add Provider** button
        2. Select your provider, such as Google AI Studio or OpenRouter.
      </Step>

      <Step title="Enter and test API key" stepNumber="3.3">
        1. A configuration window will appear
        2. Paste your API key into the field (starts with `sk-` or similar)
        3. Click the **Test Connection** button - you should see a green "Success" message
        4. Click **Save**

        You're now ready to use AI models in Cherry Studio.
      </Step>
    </Steps>
  </Step>

  <Step title="Optional: additional API providers" stepNumber="4">
    ### Optional Providers for Specific Models [#optional-providers-for-specific-models]

    OpenRouter provides access to most models you'll need. You may also want to configure additional providers for specific models or embedding services:

    <Steps titleSize="h3">
      <Step title="DeepSeek provider" stepNumber="4.1">
        Optional: if you want direct access to DeepSeek models:

        1. Click **Add Provider** → **DeepSeek**
        2. Create account at [platform.deepseek.com](https://platform.deepseek.com)
        3. Recommended Model: `deepseek-v4-flash` if it is available; otherwise choose the DeepSeek model your provider marks as the default or recommended option.
        4. Note: You can also access all DeepSeek models via OpenRouter.
      </Step>

      <Step title="Moonshot AI (Kimi)" stepNumber="4.2">
        Optional: for direct access to Kimi models:

        1. Click **Add Provider** → **Custom**
        2. Name: "Moonshot AI (Kimi)"
        3. Create account at [platform.moonshot.ai](https://platform.moonshot.ai)
        4. Base URL: `https://api.moonshot.ai/v1`
        5. Recommended Model: `kimi-k2.7-code` for coding tasks, or `kimi-k2.6` for general multimodal work
        6. Note: You can also access Kimi models via OpenRouter.
      </Step>

      <Step title="Google AI Studio provider" stepNumber="4.3">
        Recommended free backup for generous daily limits:

        1. Create account at [aistudio.google.com](https://aistudio.google.com)
        2. Get API key at [aistudio.google.com/app/apikey](https://aistudio.google.com/app/apikey)
        3. In Cherry Studio: **Add Provider** → **Google Gemini**
        4. Paste your API key (starts with `AIza…`)

        Available models:

        * `gemini-3.5-flash` (stable default for strong general work)
        * `gemini-3.1-pro-preview` (preview for complex analysis)
        * `gemini-3-flash-preview` (preview for lower-cost frontier-class work)
        * Gemini embedding models (document similarity)

        Use cases:

        * Processing large literature collections (1M token context)
        * Backup when course API credits are low
        * Cost-free experimentation
        * Document embeddings and semantic search

        Daily limits reset at midnight Pacific Time.
      </Step>
    </Steps>
  </Step>

  <Step title="Which models should I add?">
    Now that you have configured your API providers, choose which models to add.

    For recommendations on models, costs, and configuration, see the [AI Model Reference Guide](/docs/implementation/core-references/ai-model-reference-guide).
  </Step>

  <Step title="MCP Servers for research access" stepNumber="5">
    ### What Are MCPs? [#what-are-mcps]

    MCP (Model Context Protocol) gives an AI client access to external tools and data. Without MCPs, the model only has the conversation context. With MCPs, it can:

    Examples of what MCPs enable:

    * search your Zotero library: "Find all papers about organizational learning from 2020-2024"
    * read and write files: "Analyze the methodology section in Chapter3.docx"
    * search the web in real time: "What's the latest research on AI in education published this month?"
    * use structured reasoning: "Break down this complex theory comparison in 5 structured steps"
    * ask another model: "Get Gemini's perspective on this analysis" (via Vox MCP)

    MCPs let the model work with sources, files, and tools that are outside the chat window.

    ***

    ### Recommended MCPs for Research [#recommended-mcps-for-research]

    Essential MCPs:

    * `@cherry/filesystem` - lets the model read your files and analyze documents
    * `@cherry/sequentialthinking` - supports step-by-step structured reasoning

    Useful additions:

    * Zotero MCP - direct library access and search
    * Web Search MCP - current web information

    Advanced MCPs:

    * [Lotus Wisdom MCP](/docs/toolkit/lotus-wisdom-mcp) - contemplative problem-solving
    * [Vox MCP](/docs/toolkit/vox-mcp) - multi-model access across 8+ providers

    For installation instructions, see the [MCP Explorer Guide](/docs/implementation/ai-environment-setup/mcp-explorer-guide). [Session 2](/docs/case-studies/systematic-reviews/session-2-ai-powered-practice) covers the course setup in depth.

    ***

    ### How to Install MCPs [#how-to-install-mcps]

    In Cherry Studio:

    1. Settings → MCP Servers
    2. Click "Add Server"
    3. Choose from library or paste MCP URL
    4. Configure and test

    To explore available MCPs, see [MCP Explorer Guide](/docs/implementation/ai-environment-setup/mcp-explorer-guide) for:

    * Complete MCP catalog
    * Installation instructions for each MCP
    * Cherry Studio, Claude Code, and other client configs
    * Use cases and examples

    Official MCP docs: [Cherry Studio MCP Guide](https://docs.cherry-ai.com/docs/en-us/advanced-basic/mcp/install) | [MCP Protocol](https://modelcontextprotocol.io/)
  </Step>

  <Step title="Code Tools for CLI agents">
    ### Access CLI Power from the GUI [#access-cli-power-from-the-gui]

    Cherry Studio v1.5.7+ includes Code Tools. This feature lets you launch command-line AI agents directly from the Cherry Studio interface. Supported agents include Claude Code, Antigravity CLI, Qwen Code, and OpenAI Codex.

    Why use Code Tools?

    * Access CLI agent capabilities without leaving Cherry Studio
    * No separate terminal setup needed
    * Integrates with your API keys and models
    * Works well for file-based research workflows

    <Steps>
      <Step title="Enable Code Tools">
        1. Ensure you're running Cherry Studio v1.5.7 or higher
        2. Settings → Navigation → Set navigation bar to **Top position**
        3. Create a new tab or conversation
        4. Click the **Code** (\</>) icon in the toolbar
      </Step>

      <Step title="Select a CLI agent">
        Choose from available CLI tools:

        * Claude Code: Premium, excellent for research workflows
        * Antigravity CLI: Google's terminal-agent tool, the successor to the former consumer Gemini CLI
        * Qwen Code: Alibaba's open-source alternative
        * OpenAI Codex: GPT-based coding agent

        For Research Memex, we recommend:

        * Beginners → Cherry Studio first, then Antigravity CLI if you want Google's terminal agent
        * Advanced → Claude Code
        * Experimenters → Qwen Code (open source)
      </Step>

      <Step title="Configure and launch">
        1. Select a compatible AI model from your configured providers
        2. Set working directory (your research project folder)
        3. Configure environment variables if needed
        4. Click **Launch Agent**
        5. The CLI agent runs in an embedded terminal within Cherry Studio.

        For a detailed tutorial, see the [Cherry Studio Code Tools documentation](https://docs.cherry-ai.com/docs/en-us/advanced-basic/code-tools).
      </Step>
    </Steps>

    <Warning>
      Token usage: Code Tools can consume significant API tokens. Monitor usage carefully, especially with complex file operations.
    </Warning>

    When to use Code Tools vs standalone CLI:

    * use Code Tools when you want GUI convenience and integrated workflow
    * use a standalone CLI when you prefer to work in a terminal and want full control

    For standalone CLI setup, see:

    * [Claude Code Guide](/docs/implementation/agentic-ai-tools/claude-code-setup-guide)
    * [Antigravity CLI Guide](/docs/implementation/agentic-ai-tools/antigravity-cli-setup-guide)
    * [OpenCode Guide](/docs/implementation/agentic-ai-tools/opencode-setup-guide)
  </Step>

  <Step title="Test your setup" stepNumber="6">
    <Steps titleSize="h3">
      <Step title="Create test conversation" stepNumber="6.1">
        1. Click **New Chat** in the sidebar

        2. Select a model (start with Gemini 3.5 Flash, Claude Sonnet 5, or your provider's current default DeepSeek model)

        3. Type this test prompt:

           ```
           Please summarize the key components of a systematic review
           according to PRISMA guidelines in 3 bullet points.
           ```

        4. Press Enter or click Send

        Expected response: you should receive a concise summary within 5-10 seconds.
      </Step>

      <Step title="Verify model access" stepNumber="6.2">
        Test each configured model:

        1. Create new conversation
        2. Select different model from dropdown
        3. Send same test prompt
        4. Compare responses
      </Step>

      <Step title="Test MCP tools" stepNumber="6.3">
        Verify MCP servers are working:

        1. Test Zotero: "Search my Zotero for systematic review papers"
        2. Test Sequential Thinking: "Help me plan a literature review in 5 steps using sequential thinking"
        3. Test Web Search: "Find recent papers on AI in management"

        Expected: each command should return relevant results.
      </Step>
    </Steps>
  </Step>

  <Step title="Set up Knowledge Base" stepNumber="7">
    <Steps titleSize="h3">
      <Step title="Prepare your documents" stepNumber="7.1">
        1. Export your curated papers from Zotero as PDFs
        2. Create a folder: `systematic-review-papers`
        3. Place all PDFs in this folder
      </Step>

      <Step title="Create Knowledge Base in Cherry Studio" stepNumber="7.2">
        1. Click **Knowledge Base** in sidebar
        2. Click **Create New Collection**
        3. Name it: "My Systematic Review"
        4. Click **Add Documents**
        5. Select your PDF folder
        6. Wait for processing (1-2 min per 10 papers)

        Advanced options:

        * OCR processing: enable for scanned PDFs (requires v1.4.8+)
        * intent recognition: improves search accuracy with stronger models
        * multiple formats: supports PDF, TXT, Markdown, Word, and other formats

        See: [Knowledge Base Documentation](https://docs.cherry-ai.com/docs/en-us/knowledge-base/knowledge-base) | [Document Preprocessing](https://docs.cherry-ai.com/docs/en-us/knowledge-base/document-preprocessing)
      </Step>

      <Step title="Enable Knowledge Base in conversations" stepNumber="7.3">
        1. Start new conversation
        2. Click the **Knowledge** icon in the chat toolbar
        3. Select your collection
        4. The AI now has access to your papers.

        Tip: enable "Intent Recognition" in knowledge base settings for more accurate search results when asking complex research questions.
      </Step>
    </Steps>
  </Step>

  <Step title="Knowledge management with Obsidian" stepNumber="8">
    <Steps titleSize="h3">
      <Step title="Why Obsidian?" stepNumber="8.1">
        Obsidian is a markdown editor for connected research notes:

        * local storage: your notes stay on your computer
        * bidirectional linking: connect ideas across papers
        * Zotero integration: citation management
        * graph view: visualize connections in your research
        * MCP accessibility: AI can read your knowledge base
      </Step>

      <Step title="Quick setup overview" stepNumber="8.2">
        For detailed instructions, see the [Obsidian Setup Guide](/docs/implementation/foundational-setup/obsidian-setup-guide).

        #### Essential steps: [#essential-steps]

        1. Install Obsidian from [obsidian.md](https://obsidian.md)
        2. Create vault: "Systematic-Review-Research"
        3. Install plugins:
           * Zotero Integration (multiple options available)
           * Dataview (for literature tables)
           * Local REST API (for MCP access)
        4. Configure integration with Zotero (requires Better BibTeX)
        5. Set up MCP for Cherry Studio access
      </Step>

      <Step title="Cherry Studio to Obsidian workflow" stepNumber="8.3">
        #### Set Up Folder Structure [#set-up-folder-structure]

        Create this structure in your Obsidian vault:

        ```text
        /Research/
          /01-Literature-Notes/      # Individual paper notes from Zotero
          /02-AI-Conversations/       # Exported Cherry Studio chats
          /03-Synthesis/             # Your analysis and connections
          /04-Protocol/              # Review protocol development
          /05-Daily-Notes/           # Research journal
          /Templates/                # Note templates
        ```

        #### Export from Cherry Studio to Obsidian [#export-from-cherry-studio-to-obsidian]

        1. In Cherry Studio conversation:
           * Click **Export** button (or `Cmd/Ctrl + E`)
           * Choose **Markdown** format
           * Select **Save to Folder**
           * Navigate to `/02-AI-Conversations/`
           * Name format: `YYYY-MM-DD-Topic.md`

        2. The exported file includes:
           * Complete conversation history
           * Model used and timestamps
           * Any code blocks or tables
           * Referenced papers (if using Zotero MCP)

        #### Create Literature Note Template [#create-literature-note-template]

        Save this in `/Templates/literature-note.md`:

        ```markdown
        # {{title}}

        ## Metadata
        - **Authors**: {{authors}}
        - **Year**: {{year}}
        - **Journal**: {{publicationTitle}}
        - **DOI**: {{DOI}}
        - **Tags**: {{tags}}
        - **Zotero**: [Open in Zotero]({{zoteroLink}})

        ## Summary
        *AI-generated or your summary*

        ## Key Contributions
        -

        ## Methodology
        -

        ## Limitations
        -

        ## Relevance to My Research
        -

        ## Connections
        - Related papers:
        - Contradicts:
        - Extends:

        ## Annotations
        {{annotations}}
        ```
      </Step>

      <Step title="Bidirectional workflow benefits" stepNumber="8.4">
        * From Zotero to Obsidian: Import papers with annotations
        * From Cherry Studio to Obsidian: Export AI analysis
        * Within Obsidian: Link papers, find patterns, build arguments
        * Back to Cherry Studio: Copy synthesis for further AI analysis

        Advanced integration: Cherry Studio can also connect directly to Obsidian via MCP or data settings. See: [Cherry Studio Obsidian Integration](https://docs.cherry-ai.com/docs/en-us/pre-basic/data-settings/obsidian)
      </Step>
    </Steps>
  </Step>

  <Step title="Troubleshooting" stepNumber="9">
    <Steps titleSize="h3">
      <Step title="'API Key Invalid' Error" stepNumber="9.1">
        * Double-check you copied the key completely, with no extra spaces
        * Ensure you have credits in your account
        * Try regenerating the API key
      </Step>

      <Step title="'Rate Limit Exceeded'" stepNumber="9.2">
        * Wait 60 seconds and try again
        * Switch to a different model temporarily
        * Check your API provider's rate limits
      </Step>

      <Step title="'Connection Failed'" stepNumber="9.3">
        * Check internet connection
        * Verify firewall isn't blocking Cherry Studio
        * Try using a different API provider
      </Step>

      <Step title="Knowledge Base not working" stepNumber="9.4">
        * Ensure PDFs are text-based (not scanned images)
        * Check file size (max 10MB per file recommended)
        * Try re-importing documents
      </Step>

      <Step title="Model not responding" stepNumber="9.5">
        * Check API key configuration
        * Verify you have credits remaining
        * Try a different model to isolate issue
      </Step>
    </Steps>
  </Step>

  <Step title="Quick reference card" stepNumber="10">
    <Steps titleSize="h3">
      <Step title="Keyboard shortcuts" stepNumber="10.1">
        * **New Chat**: `Cmd/Ctrl + N`
        * **Fork Conversation**: `Cmd/Ctrl + Shift + F`
        * **Search Conversations**: `Cmd/Ctrl + F`
        * **Export Chat**: `Cmd/Ctrl + E`
        * **Settings**: `Cmd/Ctrl + ,`
      </Step>

      <Step title="Document processing options comparison" stepNumber="10.2">
        | Feature       | MinerU (Free) | Mistral API    | Direct Text |
        | ------------- | ------------- | -------------- | ----------- |
        | Daily Limit   | 500 documents | Unlimited      | Unlimited   |
        | Cost          | Free          | $0.10-0.20/doc | Free        |
        | Quality       | Good          | Excellent      | Basic       |
        | Math Formulas | ✓ LaTeX       | ✓ LaTeX        | ✗           |
        | Tables        | ✓ Preserved   | ✓ Enhanced     | Partial     |
        | Images        | ✓ Extracted   | ✓ OCR          | ✗           |
        | Multi-column  | ✓             | ✓              | ✗           |
        | Speed         | Fast          | Moderate       | Instant     |
      </Step>
    </Steps>
  </Step>

  <Step title="Best practices" stepNumber="11">
    1. Choose the right model for your task. See the [AI Model Reference Guide](/docs/implementation/core-references/ai-model-reference-guide) for recommendations. If you are unsure, experiment with cheaper or free models first. Use expensive models when your analysis requires more capability.
    2. Fork conversations before trying different approaches. This feature is available in Cherry Studio, ChatWise, ChatGPT, and Claude.ai.
    3. Export important conversations immediately.
       * Cherry Studio and ChatWise support native export.
       * For ChatGPT, Claude.ai, or the Gemini web interface, use the [Save my Chatbot](https://save.hugocollin.com/) Chrome and Firefox extension or the [Obsidian Web Clipper](https://obsidian.md/clipper).
    4. Start a new conversation if the responses become slow or low quality.
  </Step>
</Steps>

## What's next [#whats-next]

Cherry Studio is the GUI hub. Once you're comfortable, the natural next step is a CLI agent. See the [Claude Code Setup Guide](/docs/implementation/agentic-ai-tools/claude-code-setup-guide) for paired terminal work.

### External references [#external-references]

* [Cherry AI Docs](https://docs.cherry-ai.com/docs/en-us)
* [MCP Installation](https://docs.cherry-ai.com/docs/en-us/advanced-basic/mcp/install)
* [Knowledge Base Guide](https://docs.cherry-ai.com/docs/en-us/knowledge-base/knowledge-base)
* [GitHub Repository](https://github.com/CherryHQ/cherry-studio)
* [OpenRouter API Docs](https://openrouter.ai/docs)
* [MCP Protocol Docs](https://modelcontextprotocol.io/)

If Cherry Studio doesn't fit, ChatWise ([chatwise.ai](https://chatwise.ai)) is a close alternative. The OpenRouter playground and provider web UIs (ChatGPT, Claude.ai, Gemini) cover the gap for one-off chats.

## Checklist [#checklist]

By the end of this guide, you should have:

* Downloaded and installed Cherry Studio
* Created at least one API account (OpenRouter recommended)
* Added $5-10 in API credits
* Successfully sent a test message to any added model
* Enabled and tested at least one MCP server (Zotero, Sequential Thinking, Web Search)
* (Optional) Tested Code Tools by launching a CLI agent
* Installed Obsidian and created a vault (a folder on your computer)
* Exported a conversation to markdown format and imported it to Obsidian
* Created and tested a knowledge base in Cherry Studio with your seed papers
* (Optional) Configured OCR and intent recognition for knowledge base

## How Do You Know It's Working? [#how-do-you-know-its-working]

<AccordionGroup>
  <Accordion title="Success Indicators" icon="circle-check">
    * API responds within 5 seconds
    * Outputs include specific citations with page numbers
    * Tool connections verified with test queries
    * No error messages in console/logs
    * Workflow completes end-to-end without manual intervention
    * Output quality matches or exceeds manual work
  </Accordion>

  <Accordion title="Warning Signs" icon="triangle-exclamation">
    * Generic, vague responses ("very important," "significant impact")
    * Missing or incorrect citations
    * Suspiciously smooth narratives (no contradictions)
    * Error messages or connection timeouts
    * Repeated failures at same step
    * Output quality below manual baseline
  </Accordion>

  <Accordion title="Quick Diagnostic" icon="wrench">
    If something's not working:

    1. **Test connection:** Send simple query, verify response
    2. **Check logs:** Look for error messages
    3. **Verify credentials:** API keys valid and have credits
    4. **Restart tools:** Close and reopen application
    5. **Consult docs:** Search for specific error message
    6. **Ask for help:** Consult [llms.txt](/llms.txt) or email instructor
  </Accordion>
</AccordionGroup>

***

<Card title="For more information">
  If you plan to experiment with command‑line tools or provider‑specific keys later, see the [CLI Setup Guide](/docs/implementation/ai-environment-setup/cli-setup-guide) (optional).

  For API key setup and provider configuration, see the [API Keys Setup Guide](/docs/implementation/ai-environment-setup/api-keys-setup-guide).

  For model selection and recommended settings, refer to the [AI Model Reference Guide](/docs/implementation/core-references/ai-model-reference-guide). The guide covers reasoning effort, thinking level, and when to leave sampling defaults alone.
</Card>