# How to Add Custom MCP Servers to Chat-MCP: A Complete Configuration Guide

> Effortlessly add custom MCP servers to Chat-MCP by configuring config.json. This guide shows you how to integrate new servers without code changes.

- Repository: [AIQL/chat-mcp](https://github.com/ai-ql/chat-mcp)
- Tags: how-to-guide
- Published: 2026-02-23

---

**You can add custom MCP servers to Chat-MCP by editing the [`src/main/config.json`](https://github.com/ai-ql/chat-mcp/blob/main/src/main/config.json) file to include new entries under the `mcpServers` object with `command` and `args` properties, requiring no changes to the TypeScript source code.**

Chat-MCP is an open-source desktop application that connects to Model Context Protocol (MCP) servers to extend AI chat capabilities with external tools and resources. While the application ships with the default `server-everything` configuration, the architecture supports unlimited custom MCP servers through a simple JSON configuration system.

## Understanding the MCP Server Configuration Architecture

The Chat-MCP application uses a three-layer architecture to discover, initialize, and expose MCP servers to the user interface.

### The Central Configuration File (config.json)

All MCP server definitions reside in **[`src/main/config.json`](https://github.com/ai-ql/chat-mcp/blob/main/src/main/config.json)**. This JSON file contains a top-level `mcpServers` object where each key represents a unique server identifier, and each value specifies how to launch that server.

```json
{
  "mcpServers": {
    "everything": {
      "command": "npx",
      "args": [
        "-y",
        "@modelcontextprotocol/server-everything"
      ]
    }
  }
}

```

### Main Process Initialization (main.ts)

The main Electron process reads the configuration at startup. In **[`src/main/main.ts`](https://github.com/ai-ql/chat-mcp/blob/main/src/main/main.ts)**, the `readConfig` function (lines 44-53) parses [`config.json`](https://github.com/ai-ql/chat-mcp/blob/main/config.json), and the `initializeClient` function (lines 60-78) creates a new MCP client for each server entry.

The initialization process:
1. Spawns the specified `command` with the provided `args`
2. Establishes JSON-RPC communication over stdio
3. Registers IPC handlers so the renderer process can invoke server methods

### Preload Bridge to Renderer (preload.ts)

The **[`src/preload/preload.ts`](https://github.com/ai-ql/chat-mcp/blob/main/src/preload/preload.ts)** script exposes each configured server to the frontend under the global `window.mcpServers` object. This allows the renderer to call tools, prompts, and resources using a promise-based API without direct access to Node.js APIs.

## Step-by-Step Guide to Adding Custom MCP Servers

You can extend Chat-MCP with any MCP-compatible server by modifying only the configuration file.

### Editing the Configuration File

To add a custom server:

1. Open [`src/main/config.json`](https://github.com/ai-ql/chat-mcp/blob/main/src/main/config.json) in your text editor
2. Locate the `mcpServers` object
3. Add a new key with your server name (e.g., `filesystem`, `puppeteer`, `custom-api`)
4. Provide the `command` string (e.g., `npx`, `node`, `python`)
5. Provide the `args` array containing arguments for the command

### Adding a Filesystem Server Example

The following configuration adds the official MCP filesystem server to enable file operations within Chat-MCP:

```json
{
  "mcpServers": {
    "everything": {
      "command": "npx",
      "args": [
        "-y",
        "@modelcontextprotocol/server-everything"
      ]
    },
    "filesystem": {
      "command": "node",
      "args": [
        "node_modules/@modelcontextprotocol/server-filesystem/dist/index.js",
        "/home/user/documents"
      ]
    }
  }
}

```

**Key details:**
- The `command` uses `node` because this server runs as a local JavaScript file rather than an npx package
- The first argument points to the compiled server entry point
- The second argument specifies the absolute path to the directory the server will expose to the AI

### Adding an NPM-Based Server (Puppeteer)

For servers distributed via npm, use the `npx` command with the `-y` flag to auto-install:

```bash

# Install the server package locally (optional but recommended)

npm install @modelcontextprotocol/server-puppeteer

```

```json
{
  "mcpServers": {
    "everything": { ... },
    "puppeteer": {
      "command": "npx",
      "args": [
        "-y",
        "@modelcontextprotocol/server-puppeteer"
      ]
    }
  }
}

```

This configuration enables browser automation capabilities, exposing tools like `browser/open` and `page/screenshot` to the Chat-MCP interface.

## Accessing Custom Servers in the Renderer Process

Once configured, custom servers are immediately available in the frontend code through the `window.mcpServers` global object. The preload script dynamically exposes methods for each configured server.

```javascript
// Access the filesystem server
const { filesystem } = window.mcpServers;

// List available tools
const tools = await filesystem.tools.list();
console.log('Available filesystem tools:', tools);

// Read a file
const result = await filesystem.tools.call({
  name: "read_file",
  args: {
    path: "/home/user/documents/notes.txt"
  }
});

```

The same pattern applies to any custom server:

```javascript
// Using the puppeteer server for browser automation
const { puppeteer } = window.mcpServers;

// Take a screenshot
const screenshot = await puppeteer.tools.call({
  name: "browser/screenshot",
  args: { 
    url: "https://example.com",
    fullPage: true 
  }
});

```

All server interactions flow through the IPC bridge established in [`main.ts`](https://github.com/ai-ql/chat-mcp/blob/main/main.ts), ensuring secure communication between the renderer and the spawned server processes.

## Summary

- **Configuration location**: All MCP servers are defined in [`src/main/config.json`](https://github.com/ai-ql/chat-mcp/blob/main/src/main/config.json) under the `mcpServers` object.
- **Required properties**: Each server entry needs a `command` (executable) and `args` (array of arguments).
- **No code changes**: Adding servers requires only JSON editing; the [`main.ts`](https://github.com/ai-ql/chat-mcp/blob/main/main.ts) initialization logic automatically picks up new entries.
- **Frontend access**: Custom servers appear under `window.mcpServers` in the renderer process, exposing tools, prompts, and resources through a consistent API.
- **Supported types**: You can add npx-based servers, local Node.js scripts, Python servers, or any executable that implements the MCP protocol.

## Frequently Asked Questions

### Where is the MCP server configuration stored in Chat-MCP?

The configuration is stored in **[`src/main/config.json`](https://github.com/ai-ql/chat-mcp/blob/main/src/main/config.json)** at the project root. This JSON file contains a top-level `mcpServers` object where each key represents a server identifier and each value specifies the command and arguments needed to launch that server process.

### Do I need to modify TypeScript code to add new MCP servers?

No. The application is designed to dynamically load servers based solely on the JSON configuration. The `readConfig` and `initializeClient` functions in [`src/main/main.ts`](https://github.com/ai-ql/chat-mcp/blob/main/src/main/main.ts) automatically iterate over all entries in [`config.json`](https://github.com/ai-ql/chat-mcp/blob/main/config.json) and create clients for each one without requiring changes to the source code.

### How do I troubleshoot a custom MCP server that won't connect?

First, verify that the `command` and `args` in [`config.json`](https://github.com/ai-ql/chat-mcp/blob/main/config.json) work when run manually from your terminal. Check the Electron main process console for spawn errors or JSON-RPC connection failures. Ensure the server implements the MCP protocol correctly and communicates over stdio. You can also inspect the `window.mcpServers` object in the renderer DevTools to see if the server registered successfully.

### Can I use environment variables in the MCP server configuration?

The current implementation reads the `command` and `args` array directly from the JSON file without expansion. To use environment variables, you would need to wrap your server launch in a shell script or modify the `initializeClient` function in [`src/main/main.ts`](https://github.com/ai-ql/chat-mcp/blob/main/src/main/main.ts) to resolve variables before spawning the process.