Skip to content

Agentic AI Tools

Cherry Studio Setup Guide

Cherry Studio is useful when a research workflow needs chat, files, models, and MCP servers in one interface.

Beginner · 20–30 min · Model access required

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

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
  • Agent Workspace for a first file-touching agent without a terminal, and a Coding Companion for launching CLI agents such as Claude Code, Codex, and Kimi Code from within Cherry Studio
  • Conversation forking for exploring different analytical paths
  • Export to markdown for Obsidian integration

Official documentation: Cherry AI Docs (opens in a new tab) and the installation guide (opens in a new tab).

Before installation, follow the Workbench example and its understanding check. A working conversation is a starting point. File access, knowledge bases and agents are separate additions for tasks that need them; follow your instructor's selected mode for course work.

1

Download and install Cherry Studio

Visit Cherry Studio GitHub Releases (opens in a new tab) and download the version for your operating system.

  1. Open the downloaded .dmg file
  2. Drag Cherry Studio to your Applications folder
  3. First launch: Right-click → Open (to bypass security warning)
2

Initial configuration

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 Model Services. For API-key basics, free tiers, provider options, and setup instructions, see the API Keys Setup Guide.

3

Configure API provider

Choose the route that matches your access. The steps immediately below use a provider API key; an existing Google Cloud project can use Connect through Vertex AI instead. You do not need both.

See the API Keys Setup Guide for key-based access. For a course, use the gateway and access instructions supplied by your instructor. Do not buy credits or create a Cloud project if the assigned route already provides access.

3.1

Navigate to API settings

  1. In Cherry Studio, click the Settings icon (gear icon)
  2. In the settings menu, select Model Services
3.2

Add your provider

  1. In Model Services, choose your provider, such as Google AI Studio or OpenRouter.
  2. Open its configuration.
3.3

Enter and test API key

  1. Paste your API key into the provider's key field.
  2. Get the model list or add the IDs you intend to use.
  3. Use Test with a selected model.
  4. Turn the provider's Enable switch on. See the current provider setup guide (opens in a new tab) if your interface differs.

You can now work with AI models in Cherry Studio.

3b

Alternative: connect through Vertex AI

Choose Cherry's native Vertex AI provider to use your Google Cloud project in its chat interface. This is separate from Cherry's Gemini or Google AI Studio provider. First prepare the Cloud project. For when a course would choose this over an API key, see Model access for a class.

This route imports a service-account JSON key. If your institution does not allow those keys, choose another client or authentication route.

Configure the native provider

  1. Open Settings → Model Services and select Vertex AI.
  2. Use a service-account JSON credential authorized for this client and project. Ask the project administrator for a dedicated identity and its permissions, rather than sharing a staff credential with students.
  3. Paste the JSON into the provider's service-account JSON input. Cherry imports the account email, private key and project ID into its provider configuration. Check the project ID after import.
  4. Set the location allowed for your model and institution. The pilot used global; that is not a recommendation for every institution.
  5. Enable the provider and select a model available to your project. Use a provider-native identifier, not a gateway alias.

These fields are confirmed by Cherry's version-pinned Vertex settings source (opens in a new tab). This route does not reuse your browser's Google login.

Warning

Importing the JSON saves the credential in Cherry's configuration. Deleting the transfer file or clearing the import box does not revoke that credential. Keep it out of shared folders, screenshots, prompts and course submissions. Follow Google's service-account key guidance (opens in a new tab).

Check one conversation

Open a fresh Chat with the Vertex model selected. Leave tools and attached files out of this first check. This fictional prompt is illustrative, not the exact pilot input:

A student club needs a room for 12 people on Tuesday from 14:00
to 15:00. Return JSON with exactly four fields: purpose, people,
day, time. Use only the information given. Do not use tools.

Check the response against the prompt, then close and reopen Chat inside the app. For a permission denial, return to the project checks.

Our October 4, 2026 pilot with Cherry 2.1.3 tested 2 Vertex Chat responses and in-app history reopening. Work, Code Mate, MCP, embeddings, learner onboarding and credit offsets were not tested.

Remove access when you finish

Disable the provider and remove its saved credentials from Cherry when no longer needed. Ask the project administrator to revoke the Cloud key too, following Google's key deletion instructions (opens in a new tab). Local deletion and Cloud revocation are separate actions. Account for application backups that may retain the imported credential.

4

Optional: additional API providers

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:

4.1

DeepSeek provider

Optional: if you want direct access to DeepSeek models:

  1. Click Add Provider → DeepSeek
  2. Create account at platform.deepseek.com (opens in a new tab)
  3. Recommended Model: deepseek-flash; otherwise choose the DeepSeek model your provider marks as the default or recommended option. deepseek-v4-flash is a legacy provider-native string, not the current direct ID.
  4. Note: You can also access supported DeepSeek models via OpenRouter.
4.2

Moonshot AI (Kimi)

Optional: for direct access to Kimi models:

  1. Click Add Provider → Custom
  2. Name: "Moonshot AI (Kimi)"
  3. Create account at platform.moonshot.ai (opens in a new tab)
  4. Base URL: https://api.moonshot.ai/v1
  5. Choose a provider-listed K3-series model, such as kimi-k3.1-pro, and check its access and control requirements. Cherry compatibility and account API access are not tested here.
  6. K2-series (kimi-k2.7-code and kimi-k2.6) direct-API access is closed to newly registered users; users registered before November 1 can continue for now. Moonshot expects deprecation in late December 2026, without promising a retirement day. See the model list (opens in a new tab). OpenRouter availability is separate and is not established by this direct-provider recipe.
4.3

Google AI Studio provider

A backup route with free access to selected models and quotas:

  1. Create account at aistudio.google.com (opens in a new tab)
  2. Get API key at aistudio.google.com/app/apikey (opens in a new tab)
  3. In Cherry Studio: Add Provider → Google Gemini
  4. Paste your API key (starts with AIza…)

Available models:

  • gemini-3.8-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
  • Free-tier experimentation where the selected model and project qualify; Gemini 4 Argon is paid only. Its provider release does not establish support in this client.
  • Document embeddings and semantic search

Daily limits reset at midnight Pacific Time.

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.

5

MCP Servers for research access

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

For tasks that need these capabilities:

  • @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:

For installation instructions, see the MCP Explorer Guide. Session 2 covers the course setup in depth.

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 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 (opens in a new tab) | MCP Protocol (opens in a new tab)

Create a first agent in the Agent Workspace

From chat to agent without a terminal

The chat view is for exploration, and nothing there touches your files. The Agent Workspace, under Work in the left sidebar, is where an agent gets a working directory, tools, and a multi-step task. For most participants this is their first agent, and it is the reason this guide still starts here rather than in a terminal.

Create one:

  1. Open Work and choose Create Agent.
  2. Pick a run mode. Enhanced: Claude Agent takes a main model, a plan model, and a small model for subtasks; Fast: Pi and DeepSeek Harness take a main model only. The run mode is locked after creation.
  3. Write the system prompt: the role, what the agent may read, and what it must hand back.
  4. Attach what it needs: built-in tools, MCP servers, Skills, a knowledge base.

Give it the same literature task you gave the chat, and compare. The difference between an answer and a worked file is the lesson.

Documentation: Agent Workspace (opens in a new tab).

Coding Companion for CLI agents

Access CLI Power from the GUI

Cherry Studio's Coding Companion (Code CLI) installs, configures, and launches command-line agents from inside the app. The current list includes Claude Code, OpenAI Codex, Gemini CLI, OpenCode, Qwen Code, Kimi Code, Qoder CLI, GitHub Copilot CLI, Pi, and DeepSeek Harness; the visible items change with product updates, so treat the page's own list as authoritative.

Why use it?

  • 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

For the click path, follow the Coding Companion documentation (opens in a new tab): choose the tool, install it from the page, point it at your research project folder, and launch it in the embedded terminal.

For Research Memex, we recommend:

  • Beginners → the Agent Workspace above, then Claude Code when a task outgrows it
  • Advanced → Claude Code or Codex
  • Experimenters → OpenCode or Qwen Code (open source)

Warning

Token usage: CLI agents can consume significant API tokens. Monitor usage carefully, especially with complex file operations.

When to use the Coding Companion vs a standalone CLI:

  • use the Coding Companion 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:

6

Test your setup

6.1

Create test conversation

  1. Click New Chat in the sidebar

  2. Select a model (start with Gemini 3.8 Flash, Claude Sonnet 5.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 result: a concise summary without an authentication or model-not-found error. Latency varies by provider, model, reasoning settings, and service load; a slow response alone does not mean setup failed.

6.2

Verify model access

Test each configured model:

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

Or select several models in the input area and send once; Cherry Studio answers side by side, the quickest way to see the same prompt go different places (multi-model comparison (opens in a new tab)).

6.3

Test MCP tools

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.

7

Set up Knowledge Base

7.1

Prepare your documents

  1. Export your curated papers from Zotero as PDFs
  2. Create a folder: systematic-review-papers
  3. Place all PDFs in this folder
7.2

Create Knowledge Base in Cherry Studio

  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 (opens in a new tab) | Document Preprocessing (opens in a new tab)

7.3

Enable Knowledge Base in conversations

  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.

8

Knowledge management with Obsidian

8.1

Why Obsidian?

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
8.2

Quick setup overview

For detailed instructions, see the Obsidian Setup Guide.

Essential steps:

  1. Install Obsidian from obsidian.md (opens in a new tab)
  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
8.3

Cherry Studio to Obsidian workflow

Set Up Folder Structure

Create this structure in your Obsidian vault:

/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

  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 name and timestamps
    • Any code blocks or tables
    • Referenced papers (if using Zotero MCP)

Create Literature Note Template

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

# {{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}}
8.4

Bidirectional workflow benefits

  • 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 (opens in a new tab)

9

Troubleshooting

9.1

'API Key Invalid' Error

  • Double-check you copied the key completely, with no extra spaces
  • Ensure you have credits in your account
  • Try regenerating the API key
9.2

'Rate Limit Exceeded'

  • Wait 60 seconds and try again
  • Switch to a different model temporarily
  • Check your API provider's rate limits
9.3

'Connection Failed'

  • Check internet connection
  • Verify firewall isn't blocking Cherry Studio
  • Try using a different API provider
9.4

Knowledge Base not working

  • Ensure PDFs are text-based (not scanned images)
  • Check file size (max 10MB per file recommended)
  • Try re-importing documents
9.5

Model not responding

  • Check API key configuration
  • Verify you have credits remaining
  • Try a different model to isolate issue
10

Quick reference card

10.1

Keyboard shortcuts

  • New Chat: Cmd/Ctrl + N
  • Fork Conversation: Cmd/Ctrl + Shift + F
  • Search Conversations: Cmd/Ctrl + F
  • Export Chat: Cmd/Ctrl + E
  • Settings: Cmd/Ctrl + ,
10.2

Document processing options comparison

FeatureMinerU (Free)Mistral APIDirect Text
Daily Limit10,000 files/day*UnlimitedUnlimited
CostFree*$4/1,000 pages*Free
QualityGoodExcellentBasic
Math Formulas✓ LaTeX✓ LaTeX✗
Tables✓ Preserved✓ EnhancedPartial
Images✓ Extracted✓ OCR✗
Multi-column✓✓✗
SpeedFastModerateInstant

*Published limits and prices are endpoint-, plan-, and page-count dependent. Check MinerU's current limits (opens in a new tab) and Mistral's current OCR pricing (opens in a new tab) before a batch.

11

Best practices

  1. Choose the right model for your task. See the AI Model Reference Guide for recommendations. If you are unsure, experiment with cheaper or free models first. Work with higher-cost models when their contributions justify the expense.
  2. Fork conversations before trying different approaches. This feature is available in Cherry Studio, ChatWise, ChatGPT, and Claude.ai.
  3. Export important conversations immediately.
  4. Start a new conversation if the responses become slow or low quality.

What's 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 for paired terminal work.

External references

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

Checklist

For a first conversation:

  • I can open Cherry Studio and use the model access chosen for this task.
  • I can send a non-sensitive test passage and receive a response.
  • I can compare the response with that passage and save the input, response and my correction separately.

Check only the additions your task needs:

  • For MCP access, I tested the selected connection and checked its allowed inputs, folders and write permissions.
  • For an agent, I set its task and permissions and know where to review its output.
  • For a knowledge base, I checked retrieval against a known source passage.
  • For Markdown export, I can reopen the saved file in a text editor or Obsidian.
  • For OCR, I compared the converted passage with its original.

Unused additions are not incomplete setup. A course may specify a shared configuration; follow its brief rather than treating every feature in this guide as required.

Check the result

For more information

If you plan to experiment with command‑line tools or provider‑specific keys later, see the CLI Setup Guide (optional).

For API key setup and provider configuration, see the API Keys Setup Guide.

For model selection and recommended settings, refer to the AI Model Reference Guide. The guide covers reasoning effort, thinking level, and when to leave sampling defaults alone.

cite this page

Lin, X. (2026). Cherry Studio Setup Guide. Research Memex. https://research-memex.org/docs/implementation/agentic-ai-tools/cherry-studio-setup-guide

@misc{docs-implementation-agentic-ai-tools-cherry-studio-setup-guide-2026,
  author = {Xule Lin},
  title = {Cherry Studio Setup Guide},
  year = {2026},
  howpublished = {\url{https://research-memex.org/docs/implementation/agentic-ai-tools/cherry-studio-setup-guide}},
  note = {ORCID: 0000-0001-7885-4194}
}

one renderingthe source remains