Skip to content
MCPDev

Connect an MCP server to Cherry Studio

Spec
2026-07-28
Evidence
E1From official docs

Where to add a server

Section titled “Where to add a server”

Cherry Studio has no configuration file for you to edit. Servers are managed in the app:

Settings → MCP → MCP Servers → Add

You can create a server by hand or import it from JSON. After saving, enable the server, wait for its status to turn normal, and open its details to check the tools, resources and prompts it offers.

Then bind it to an agent, or the agent will not see it: Work → agent menu → Edit → MCP, and enable the server. Bind only the servers that agent needs; unrelated tools take up context.

Import from JSON

Section titled “Import from JSON”

The import dialog takes the same mcpServers shape as most clients.

A local (stdio) server:

{
  "mcpServers": {
    "hello-ts": {
      "type": "stdio",
      "command": "node",
      "args": ["/absolute/path/to/hello-server/src/server.ts"],
      "env": { "API_KEY": "<YOUR_API_KEY>" }
    }
  }
}

A remote (Streamable HTTP) server:

{
  "mcpServers": {
    "my-remote": {
      "type": "streamableHttp",
      "url": "https://mcp.example.com/api",
      "headers": { "Authorization": "Bearer <YOUR_TOKEN>" }
    }
  }
}

Cherry Studio stores the address as baseUrl. The import accepts either url or baseUrl, and uses baseUrl when both are present.

Cherry Studio does not expand environment variables in these values as far as we can tell from its documentation, so replace the <YOUR_…> placeholders with real values after importing. The values are stored in Cherry Studio’s settings. Cover them in screenshots and remove them before you export or share a configuration.

How Cherry Studio finds npx and uvx

Section titled “How Cherry Studio finds npx and uvx”

For npx, uvx and uv, Cherry Studio first looks them up in your login shell’s environment. If they are not there, it falls back to the copies it ships with: its built-in Bun stands in for npx (as bun x), and its built-in uv for uvx and uv.

That has two consequences:

  • You can use npx in the configuration on every OS, including Windows, without a cmd /c wrapper. Cherry Studio resolves the command itself.
  • If you see an error that uv or bun cannot be found, open Settings → Environment dependencies. That page shows whether the built-in tools are installed and has an install button for each.

Other commands, such as node or python, must be on the PATH of your login shell, or written as absolute paths.

When a server does not connect

Section titled “When a server does not connect”
  1. Enable one server at a time. Several failing at once are hard to tell apart.
  2. Open the server’s details and read its log. Fix the first error before you remove and re-add anything; if you do re-add, keep a copy of the configuration without keys.
  3. Run the same command in a terminal. If it exits, the message it prints is the cause. See the stdio checklist.
  4. If the server shows as connected but the agent cannot find its tools, check that the server is bound to that agent, that the tool is not disabled, and that no permission request is waiting. Send a new message after changing the agent.
Section titled “Related”

Sources

MCPDev is community documentation. It is not affiliated with the Model Context Protocol project or with the vendors of the clients it covers.