How to configure MCP on macOS

[aiqlcom]

Due to the numerous configuration options available on macOS, this ticket will be dedicated to tracking associated issues.

[aiqlcom]

A general guide covering multiple approaches is available at modelcontextprotocol/servers#64

I'll summarize and provide a simple method below. However, if you're looking for more comprehensive or elegant solutions, you can refer to the additional suggestions in this link.

Summary

In macOS, you cannot directly run MCP servers using the original MCP configuration files. This is typically due to path configuration issues in the macOS environment.

Let me use npx as an example. After installing Node.js, you'll usually see the following prompt, which indicates the relevant paths:

When you launch your application directly from the Terminal, for example:

/Applications/tuui.app/Contents/MacOS/tuui  

It usually runs successfully and can start the associated MCP Servers without issues.

However, if you open the application by double-clicking its icon in the Application Docker, you might encounter errors like spawn npx ENOENT or MCP error -32000: Connection closed.

This happens because the system cannot locate the required commands or local packages due to differences in the environment variables.

To fix this, you’ll need to modify the app’s config file, typically located at:

/Applications/tuui.app/Contents/Resources/assets/config.json 

Add or adjust the PATH in the env section, for example:

{
  "mcpServers": {
    "everything": {
      "command": "npx",
      "args": [
        "-y",
        "@modelcontextprotocol/server-everything"
      ],
      "env": {
+        "PATH": "/usr/local/bin/:bin"
      }
    }
  }
}

After saving the changes, you should be able to launch the app by double-clicking and use MCP Server functionality.

Since this modifies the PATH, if you later run the app via the Terminal using the absolute path, you may need to revert to the original MCP config.