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

You can add custom MCP servers to Chat-MCP by editing the 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. 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.

{
  "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, the readConfig function (lines 44-53) parses 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 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 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:

{
  "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:

# Install the server package locally (optional but recommended)

npm install @modelcontextprotocol/server-puppeteer

{
  "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.

// 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:

// 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, ensuring secure communication between the renderer and the spawned server processes.

Summary

• Configuration location: All MCP servers are defined in 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 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 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 automatically iterate over all entries in 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 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 to resolve variables before spawning the process.

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