How to Configure Custom MCP Servers in Cherry Studio: A Complete Guide

You can configure custom MCP servers in Cherry Studio through the Settings → MCP interface by defining transport types (stdio, SSE, or HTTP), commands, environment variables, and activation states, which are persisted in a Redux slice and managed by the main-process MCPService.

Cherry Studio is an open-source AI client that implements the Model Context Protocol (MCP) to extend functionality with custom tools, prompts, and resources. Configuring custom MCP servers in Cherry Studio involves understanding the architecture that bridges the renderer process UI, Redux state management, and the main process service that handles transport layers.

Architecture of MCP Server Configuration

The configuration system spans four layers:

• Renderer Redux Store: Defined in src/renderer/src/store/mcp.ts, this slice maintains the array of MCPServer objects and exposes actions including addMCPServer, updateMCPServer, deleteMCPServer, and setMCPServers.

• UI Components: The McpServersList.tsx and McpSettings.tsx components in src/renderer/src/pages/settings/MCPSettings/ provide the interface for creating and editing servers.

• IPC Bridge: The useMCPServers.ts hook registers listeners on IpcChannel.Mcp_ServersChanged and IpcChannel.Mcp_AddServer to synchronize state between processes.

• Main Process Service: src/main/services/MCPService.ts creates transport clients, starts processes, and handles tool calls based on the configuration received from the renderer.

Configuration Fields and Transport Types

When you configure custom MCP servers in Cherry Studio, you define the following fields in the MCPServer object:

• name: Unique human-readable identifier.
• type: Transport protocol—stdio, sse, streamableHttp, or inMemory.
• command: For stdio servers, the executable command (e.g., npx, uvx).
• args: Array of command-line arguments, entered as newline-separated text in the UI.
• env: Environment variables passed to the process, formatted as KEY=value.
• baseUrl: HTTP endpoint for sse or streamableHttp transports.
• headers: HTTP headers for HTTP-based transports.
• registryUrl: Optional registry override for package managers (npm or pip mirrors).
• isActive: Boolean flag controlling whether the server starts automatically.

Step-by-Step Configuration Guide

Adding a Server via the UI

1. Navigate to Settings → MCP → Servers.
2. Click Add → Create to open the configuration form in McpSettings.tsx.
3. Select the Server Type (stdio, sse, or streamableHttp).
4. For stdio servers, enter the Command (e.g., uvx @myorg/my-mcp-server) and Args (one per line).
5. Configure Environment Variables in the textarea using KEY=value format.
6. Toggle the Active switch to start the server immediately.
7. Click Save to persist the configuration to the Redux store.

When you save, the updateMCPServer action updates the store, and MCPService receives the changes via IPC to manage the transport client.

Programmatic Configuration

You can configure custom MCP servers in Cherry Studio programmatically using the Redux actions directly:

import { useAppDispatch } from '@renderer/store'
import { addMCPServer } from '@renderer/store/mcp'

const dispatch = useAppDispatch()

// Add a stdio-based MCP server
dispatch(
  addMCPServer({
    id: 'my-custom-mcp-1',
    name: 'My Custom MCP',
    type: 'stdio',
    command: 'uvx',
    args: ['@myorg/my-mcp-server', '--json'],
    env: { MY_API_KEY: 'abc123' },
    isActive: true,
    isTrusted: true,
    installSource: 'custom',
  })
)

The main process automatically detects the new server through the IpcChannel.Mcp_AddServer event and initializes the client via MCPService.initClient.

Key Implementation Files

Understanding these source files helps when configuring custom MCP servers in Cherry Studio:

• src/renderer/src/store/mcp.ts: Redux slice containing MCPServer type definitions and actions (addMCPServer, updateMCPServer, deleteMCPServer).

• src/renderer/src/hooks/useMCPServers.ts: React hook providing useMCPServers and useMCPServer selectors, plus IPC listeners for IpcChannel.Mcp_ServersChanged.

• src/renderer/src/pages/settings/MCPSettings/McpServersList.tsx: UI component displaying the server list with activation toggles and version fetching via window.api.mcp.getServerVersion.

• src/renderer/src/pages/settings/MCPSettings/McpSettings.tsx: Detailed configuration form handling all transport types and advanced options.

• src/main/services/MCPService.ts: Main-process service that creates transports (StdioClientTransport, SSEClientTransport, StreamableHTTPClientTransport, InMemoryTransport), manages server lifecycle, and handles tool calls.

Summary

• Cherry Studio stores MCP server configurations in a Redux slice at src/renderer/src/store/mcp.ts with actions for adding, updating, and deleting servers.
• The main process handles actual server execution through MCPService.ts, supporting stdio, SSE, streamable HTTP, and in-memory transports.
• You can configure custom MCP servers in Cherry Studio through the Settings → MCP → Servers UI or programmatically via Redux actions like addMCPServer.
• Configuration fields include command, args, environment variables, registry URLs, and HTTP headers, allowing flexible integration with local binaries or remote endpoints.
• Changes are synchronized between renderer and main process via IPC channels (IpcChannel.Mcp_ServersChanged), ensuring the active server list stays consistent across the application.

Frequently Asked Questions

What transport types are supported for MCP servers in Cherry Studio?

Cherry Studio supports four transport types defined in the MCPServer type: stdio for local command execution, sse for Server-Sent Events endpoints, streamableHttp for HTTP-based JSON-RPC, and inMemory for built-in servers like memory and browser tools. The transport is selected via the type field and configured in McpSettings.tsx.

How do I restart an MCP server after editing its configuration?

When you save changes in McpSettings.tsx, the updateMCPServer Redux action persists the new configuration. If the server was active, the code calls window.api.mcp.restartServer(mcpServer), which triggers MCPService in the main process to stop the existing transport and reinitialize it with the updated parameters.

Can I configure MCP servers programmatically without using the UI?

Yes, you can import addMCPServer from src/renderer/src/store/mcp and dispatch it with a complete MCPServer object. This approach bypasses the McpServersList UI and immediately adds the server to the Redux store, triggering the same IPC synchronization to the main process that handles the actual server lifecycle.

Where are MCP server configurations persisted in Cherry Studio?

Server configurations are stored in the Redux slice at src/renderer/src/store/mcp.ts and persisted to the user data folder via Redux-persist during the application boot sequence. The main process accesses these definitions through IPC calls like getMCPServersFromRedux, ensuring the renderer and main process maintain synchronized state across application restarts.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}