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

> Learn to configure custom MCP servers in Cherry Studio. Define transport types commands environment variables and activation states via the Settings MCP interface.

- Repository: [CherryHQ/cherry-studio](https://github.com/cherryhq/cherry-studio)
- Tags: how-to-guide
- Published: 2026-02-27

---

**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`](https://github.com/cherryhq/cherry-studio/blob/main/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`](https://github.com/cherryhq/cherry-studio/blob/main/McpServersList.tsx) and [`McpSettings.tsx`](https://github.com/cherryhq/cherry-studio/blob/main/McpSettings.tsx) components in `src/renderer/src/pages/settings/MCPSettings/` provide the interface for creating and editing servers.

- **IPC Bridge**: The [`useMCPServers.ts`](https://github.com/cherryhq/cherry-studio/blob/main/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`](https://github.com/cherryhq/cherry-studio/blob/main/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`](https://github.com/cherryhq/cherry-studio/blob/main/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:

```typescript
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`](https://github.com/cherryhq/cherry-studio/blob/main/src/renderer/src/store/mcp.ts)**: Redux slice containing `MCPServer` type definitions and actions (`addMCPServer`, `updateMCPServer`, `deleteMCPServer`).

- **[`src/renderer/src/hooks/useMCPServers.ts`](https://github.com/cherryhq/cherry-studio/blob/main/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`](https://github.com/cherryhq/cherry-studio/blob/main/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`](https://github.com/cherryhq/cherry-studio/blob/main/src/renderer/src/pages/settings/MCPSettings/McpSettings.tsx)**: Detailed configuration form handling all transport types and advanced options.

- **[`src/main/services/MCPService.ts`](https://github.com/cherryhq/cherry-studio/blob/main/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`](https://github.com/cherryhq/cherry-studio/blob/main/src/renderer/src/store/mcp.ts) with actions for adding, updating, and deleting servers.
- The **main process** handles actual server execution through [`MCPService.ts`](https://github.com/cherryhq/cherry-studio/blob/main/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`](https://github.com/cherryhq/cherry-studio/blob/main/McpSettings.tsx).

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

When you save changes in [`McpSettings.tsx`](https://github.com/cherryhq/cherry-studio/blob/main/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`](https://github.com/cherryhq/cherry-studio/blob/main/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.