Skip to content

MCP Server not starting on macOS and Linux

Jump to bottom
Nicolas Bonamy edited this page May 7, 2025 · 1 revision

Diagnosing

In most cases when a MCP server is not working, it is related to a PATH issue.

You should be able to diagnose this by clicking the ❌ icon or check the log file:

image

To check the log file, open a Terminal window and cd ~/Library/Logs/Witsy/ (cd ~/.config/Witsy/logs on Linux). Here you should see the main.log file and you should be able to see a line such as:

[2025-04-27 09:25:16.440] [error] Failed to connect to MCP server bunx index.js: Error: spawn bunx ENOENT
    at ChildProcess._handle.onexit (node:internal/child_process:286:19)
    at onErrorNT (node:internal/child_process:484:16)
    at processTicksAndRejections (node:internal/process/task_queues:82:21)
    at runNextTicks (node:internal/process/task_queues:64:3)
    at listOnTimeout (node:internal/timers:545:9)
    at process.processTimers (node:internal/timers:519:7)

The key here is ENOENT meaning the program (here bunx) was not found.

Fixing

Hereafter we will use bunx as an example but the same procedure would be valid if the error message indicates node, npm, npx, uv, uvx...

The first thing to check is that bunx is accessible using the PATH variable. To do this, in the terminal window, type which bunx. You should see something like:

$ which bunx
/opt/homebrew/bin/bunx

If you see an empty line it means than bunx is not accessible in your PATH and therefore there is no way Witsy can run it. You need to fix your PATH first. Given that this depends on your shell, this goes beyond this article. Google should help you there.

Not that we know the location of bunx we need to check if this location is visible to Witsy. In the same terminal window, type the following command:

macOS: grep 'Fixing PATH' ~/Library/Logs/Witsy/main.log | tail -1
Linux: grep 'Fixing PATH' ~/.config/Witsy/logs/main.log | tail -1

The output should contain a list of directories separated by :. Example:

[2025-04-27 09:18:21.777] [info]  Fixing PATH: ~/bin:/usr/local/sbin:/usr/local/bin:/System/Cryptexes/App/usr/bin:/usr/bin:/bin:/usr/sbin:/sbin:...

Check if the location of bunx (/opt/homebrew/bin in our example) is included in that list. An easy way do that is (replace /opt/homebrew/bin with the result of your which command):

macOS: grep 'Fixing PATH' ~/Library/Logs/Witsy/main.log | tail -1 | grep /opt/homebrew/bin
Linux: grep 'Fixing PATH' ~/.config/Witsy/logs/main.log | tail -1 | grep /opt/homebrew/bin

If the output of that command is empty it means that your PATH variable does not contain the location and that your shell is doing something more to find bunx. That is often the case when you are using nvm. In that case, you need to add the location of bunx to your global PATH. Given that this depends on your shell, this goes beyond this article. Google should help you there.

If you found the location of bunx in the Fixing PATH line, then something else is happening and there is more to do to understand what is going on. Please include the results of the commands above in your issue.

Clone this wiki locally