Mintplex-Labs/anything-llm
1
0
Fork 0
mirror of https://github.com/Mintplex-Labs/anything-llm.git synced 2026-07-19 14:13:35 -04:00
Code Issues 328 Packages Projects Releases 10 Wiki Activity

[GH-ISSUE #3904] [BUG]: MCP Servers Fail to Start When Launched via GUI on macOS #2489

New Issue
Closed
opened 2026-02-22 18:29:54 -05:00 by yindo · 3 comments
yindo commented 2026-02-22 18:29:54 -05:00
Owner
Copy Link
Copy Source

Originally created by @PaoloC68 on GitHub (May 28, 2025).
Original GitHub issue: https://github.com/Mintplex-Labs/anything-llm/issues/3904

How are you running AnythingLLM?

Desktop

What happened?

Bug Description

MCP servers fail to start when AnythingLLM is launched via the GUI application, but work correctly when launched from the command line. All MCP servers report the error:

Failed to start MCP server: [server-name] [-32000] MCP error -32000: Connection closed

Are there known steps to reproduce?

Bug Report: MCP Servers Fail to Start When Launched via GUI on macOS

Environment

  • OS: macOS (Darwin)
  • AnythingLLM Version: [Version 1.8.1-r2 (1.8.1-r2)]
  • Node.js: v23.11.0 (installed via Homebrew)
  • Installation Method: Desktop App

Bug Description

MCP servers fail to start when AnythingLLM is launched via the GUI application, but work correctly when launched from the command line. All MCP servers report the error:

Failed to start MCP server: [server-name] [-32000] MCP error -32000: Connection closed

Root Cause

The GUI application launches with a severely restricted environment that lacks access to Node.js binaries:

GUI Environment:

PATH: /usr/bin:/bin:/usr/sbin:/sbin
NODE_PATH: (empty)
PWD: /
which node: (not found)
which npx: (not found)

Command Line Environment:

PATH: /usr/local/bin:/usr/local/Cellar/node/23.11.0/bin:/usr/bin:/bin:/usr/sbin:/sbin
NODE_PATH: /usr/local/lib/node_modules
node: /usr/local/bin/node
npx: /usr/local/bin/npx

Steps to Reproduce

  1. Install Node.js via Homebrew
  2. Configure MCP servers in AnythingLLM with standard configuration: 
    {
  "mcpServers": {
    "jetbrains": {
      "command": "/usr/local/bin/npx",
      "args": ["-y", "@jetbrains/mcp-proxy"],
      "env": {
        "MCP_ACTIVE": "true",
        "NODE_PATH": "/usr/local/lib/node_modules",
        "PATH": "/usr/local/bin:/usr/bin:/bin:/usr/sbin:/sbin"
      }
    }
  }
}
  3. Launch AnythingLLM via GUI → MCP servers fail
  4. Launch AnythingLLM via command line (./AnythingLLM) → MCP servers work

Workaround

Use shell wrappers instead of direct npx commands:

{
  "mcpServers": {
    "jetbrains": {
      "command": "/bin/sh",
      "args": [
        "-c",
        "export PATH='/usr/local/bin:/usr/local/Cellar/node/23.11.0/bin:/usr/bin:/bin:/usr/sbin:/sbin' && export NODE_PATH='/usr/local/lib/node_modules' && export MCP_ACTIVE='true' && /usr/local/bin/npx -y @jetbrains/mcp-proxy"
      ]
    },
    "brave-search": {
      "command": "/bin/sh",
      "args": [
        "-c",
        "export PATH='/usr/local/bin:/usr/local/Cellar/node/23.11.0/bin:/usr/bin:/bin:/usr/sbin:/sbin' && BRAVE_API_KEY=YOUR_API_KEY /usr/local/bin/npx -y @modelcontextprotocol/server-brave-search"
      ]
    }
  }
}

Expected Behavior

MCP servers should start successfully regardless of whether AnythingLLM is launched via GUI or command line.

Proposed Solution

The Electron app should inherit or properly set up the user's shell environment when launching MCP server processes. Consider:

  1. Environment Inheritance: Ensure the app inherits the user's full shell environment
  2. PATH Detection: Automatically detect common Node.js installation paths (/usr/local/bin, Homebrew paths, etc.)
  3. Better Error Messages: Provide more specific error messages when Node.js binaries aren't found
  4. Documentation: Add troubleshooting section for environment-related MCP issues

Additional Context

This is a common issue with Electron applications on macOS where GUI apps don't inherit the terminal's environment. The env parameter in MCP server configurations appears to be insufficient for npx to function properly in the restricted GUI environment.

Labels: bug, macos, mcp, electron, desktop-app

Originally created by @PaoloC68 on GitHub (May 28, 2025). Original GitHub issue: https://github.com/Mintplex-Labs/anything-llm/issues/3904 ### How are you running AnythingLLM? Desktop ### What happened? ### **Bug Description** MCP servers fail to start when AnythingLLM is launched via the GUI application, but work correctly when launched from the command line. All MCP servers report the error: ``` Failed to start MCP server: [server-name] [-32000] MCP error -32000: Connection closed ``` ### Are there known steps to reproduce? ## Bug Report: MCP Servers Fail to Start When Launched via GUI on macOS ### **Environment** - **OS**: macOS (Darwin) - **AnythingLLM Version**: [Version 1.8.1-r2 (1.8.1-r2)] - **Node.js**: v23.11.0 (installed via Homebrew) - **Installation Method**: Desktop App ### **Bug Description** MCP servers fail to start when AnythingLLM is launched via the GUI application, but work correctly when launched from the command line. All MCP servers report the error: ``` Failed to start MCP server: [server-name] [-32000] MCP error -32000: Connection closed ``` ### **Root Cause** The GUI application launches with a severely restricted environment that lacks access to Node.js binaries: **GUI Environment:** ``` PATH: /usr/bin:/bin:/usr/sbin:/sbin NODE_PATH: (empty) PWD: / which node: (not found) which npx: (not found) ``` **Command Line Environment:** ``` PATH: /usr/local/bin:/usr/local/Cellar/node/23.11.0/bin:/usr/bin:/bin:/usr/sbin:/sbin NODE_PATH: /usr/local/lib/node_modules node: /usr/local/bin/node npx: /usr/local/bin/npx ``` ### **Steps to Reproduce** 1. Install Node.js via Homebrew 2. Configure MCP servers in AnythingLLM with standard configuration: ```json { "mcpServers": { "jetbrains": { "command": "/usr/local/bin/npx", "args": ["-y", "@jetbrains/mcp-proxy"], "env": { "MCP_ACTIVE": "true", "NODE_PATH": "/usr/local/lib/node_modules", "PATH": "/usr/local/bin:/usr/bin:/bin:/usr/sbin:/sbin" } } } } ``` 3. Launch AnythingLLM via GUI → MCP servers fail 4. Launch AnythingLLM via command line (`./AnythingLLM`) → MCP servers work ### **Workaround** Use shell wrappers instead of direct `npx` commands: ```json { "mcpServers": { "jetbrains": { "command": "/bin/sh", "args": [ "-c", "export PATH='/usr/local/bin:/usr/local/Cellar/node/23.11.0/bin:/usr/bin:/bin:/usr/sbin:/sbin' && export NODE_PATH='/usr/local/lib/node_modules' && export MCP_ACTIVE='true' && /usr/local/bin/npx -y @jetbrains/mcp-proxy" ] }, "brave-search": { "command": "/bin/sh", "args": [ "-c", "export PATH='/usr/local/bin:/usr/local/Cellar/node/23.11.0/bin:/usr/bin:/bin:/usr/sbin:/sbin' && BRAVE_API_KEY=YOUR_API_KEY /usr/local/bin/npx -y @modelcontextprotocol/server-brave-search" ] } } } ``` ### **Expected Behavior** MCP servers should start successfully regardless of whether AnythingLLM is launched via GUI or command line. ### **Proposed Solution** The Electron app should inherit or properly set up the user's shell environment when launching MCP server processes. Consider: 1. **Environment Inheritance**: Ensure the app inherits the user's full shell environment 2. **PATH Detection**: Automatically detect common Node.js installation paths (`/usr/local/bin`, Homebrew paths, etc.) 3. **Better Error Messages**: Provide more specific error messages when Node.js binaries aren't found 4. **Documentation**: Add troubleshooting section for environment-related MCP issues ### **Additional Context** This is a common issue with Electron applications on macOS where GUI apps don't inherit the terminal's environment. The `env` parameter in MCP server configurations appears to be insufficient for `npx` to function properly in the restricted GUI environment. --- **Labels:** `bug`, `macos`, `mcp`, `electron`, `desktop-app`
yindo added the possible bug label 2026-02-22 18:29:54 -05:00
yindo closed this issue 2026-02-22 18:29:54 -05:00
yindo commented 2026-02-22 18:29:55 -05:00
Author
Owner
Copy Link
Copy Source

@timothycarambat commented on GitHub (May 28, 2025):

All of this is mentioned in https://docs.anythingllm.com/mcp-compatibility/desktop#things-to-know-about-mcp-on-anythingllm-desktop or on the MCP discussion board

@timothycarambat commented on GitHub (May 28, 2025): All of this is mentioned in https://docs.anythingllm.com/mcp-compatibility/desktop#things-to-know-about-mcp-on-anythingllm-desktop or on the MCP discussion board
yindo commented 2026-02-22 18:29:55 -05:00
Author
Owner
Copy Link
Copy Source

@PaoloC68 commented on GitHub (May 29, 2025):

Hi @timothycarambat,

I appreciate your quick responses, but I think there might be a misunderstanding about the core issue I'm reporting. This isn't about MCP server functionality or missing dependencies - it's about a fundamental environment inheritance problem in AnythingLLM that affects multiple platforms, not just macOS.

The Core Issue: Cross-Platform Environment Inheritance Problem

The problem is that AnythingLLM doesn't properly inherit or set up execution environments when spawning MCP server processes, causing identical configurations to fail across different deployment scenarios. This affects all MCP servers that depend on external binaries (Node.js/npx, Python, etc.), regardless of their specific functionality.

Evidence Across Platforms

macOS (My case):

GUI Launch: PATH=/usr/bin:/bin:/usr/sbin:/sbin (missing Homebrew paths)
CLI Launch: PATH=/usr/local/bin:/usr/local/Cellar/node/23.11.0/bin:/usr/bin:/bin (works)

Docker/Linux (#3671 - Raspberry Pi ARM64):

  • User reports backend executing wrong commands, ignoring configured command field
  • Same -32000 Connection closed errors in containerized environment

Windows/WSL (#3703):

  • Environment variables don't pass through to WSL container
  • User confirmed: env property fails, but embedding vars in args works

Additional macOS cases (#3681, #3902):

  • Users with /opt/homebrew/bin paths experiencing identical -32000 errors
  • Working binaries in PATH but failing when spawned by AnythingLLM

Pattern Recognition Across All Reports

Looking at the issues you've closed, every single one shares the common thread of environment/process spawning problems:

  • #3902 (Playwright): Environment issue → dismissed as "chromium requirements"
  • #3681 (Python MCP): Environment issue → dismissed as "MCP tool discussion"
  • #3671 (Docker/ARM64): Environment issue → resolved by adding PATH to env
  • #3703 (WSL): Environment issue → acknowledged as legitimate problem
  • My issue: Environment issue → dismissed with doc reference

This is an AnythingLLM Architecture Issue

The MCP servers work perfectly when executed directly - they're not the problem. The issue is how AnythingLLM spawns child processes across different environments:

  1. GUI applications don't inherit shell environments properly
  2. Docker containers lack proper PATH setup
  3. WSL processes don't receive environment variables
  4. Cross-platform path differences aren't handled

Cost-Benefit Analysis

Current approach: Dismissing each report individually as platform/tool-specific issues
Result: Mounting reports, frustrated users, same root cause recurring

Proposed approach: Address the underlying process spawning architecture once
Result: Fix multiple platforms simultaneously, prevent future similar reports

Simple Reproduction (Any Platform)

I'd strongly encourage you to reproduce this on any platform:

  1. Install Node.js via system package manager (not in standard PATH)
  2. Configure any npx-based MCP server
  3. Launch AnythingLLM via GUI/container → MCP fails with -32000
  4. Launch AnythingLLM with proper environment → MCP works

This will take 5 minutes and demonstrate the cross-platform nature of the issue.

Proposed Solutions

  1. Fix process spawning: Ensure proper environment inheritance across platforms
  2. Platform-aware PATH detection: Auto-detect common installation paths per platform
  3. Better diagnostics: Show actual vs expected environment when MCP startup fails
  4. Unified documentation: Document the environment inheritance issue and workarounds

Given that this affects macOS, Linux, Docker, and Windows/WSL, and that you're spending considerable time dismissing related reports, wouldn't it be more efficient to address the root architectural issue once rather than continue handling each platform manifestation separately?

The workaround (shell wrappers) works across all platforms, proving this is a consistent process spawning issue within AnythingLLM, not platform-specific MCP problems.

Would you be willing to reproduce this issue to see the cross-platform pattern? I believe fixing this systematically will prevent a significant number of future support requests.

Thanks for your time and consideration.

@PaoloC68 commented on GitHub (May 29, 2025): Hi @timothycarambat, I appreciate your quick responses, but I think there might be a misunderstanding about the core issue I'm reporting. This isn't about MCP server functionality or missing dependencies - it's about a fundamental environment inheritance problem in AnythingLLM that affects **multiple platforms**, not just macOS. ## The Core Issue: Cross-Platform Environment Inheritance Problem The problem is that **AnythingLLM doesn't properly inherit or set up execution environments** when spawning MCP server processes, causing identical configurations to fail across different deployment scenarios. This affects **all** MCP servers that depend on external binaries (Node.js/npx, Python, etc.), regardless of their specific functionality. ## Evidence Across Platforms **macOS (My case):** ``` GUI Launch: PATH=/usr/bin:/bin:/usr/sbin:/sbin (missing Homebrew paths) CLI Launch: PATH=/usr/local/bin:/usr/local/Cellar/node/23.11.0/bin:/usr/bin:/bin (works) ``` **Docker/Linux (#3671 - Raspberry Pi ARM64):** - User reports backend executing wrong commands, ignoring configured `command` field - Same `-32000 Connection closed` errors in containerized environment **Windows/WSL (#3703):** - Environment variables don't pass through to WSL container - User confirmed: `env` property fails, but embedding vars in `args` works **Additional macOS cases (#3681, #3902):** - Users with `/opt/homebrew/bin` paths experiencing identical `-32000` errors - Working binaries in PATH but failing when spawned by AnythingLLM ## Pattern Recognition Across All Reports Looking at the issues you've closed, **every single one** shares the common thread of environment/process spawning problems: - **#3902 (Playwright)**: Environment issue → dismissed as "chromium requirements" - **#3681 (Python MCP)**: Environment issue → dismissed as "MCP tool discussion" - **#3671 (Docker/ARM64)**: Environment issue → resolved by adding PATH to env - **#3703 (WSL)**: Environment issue → acknowledged as legitimate problem - **My issue**: Environment issue → dismissed with doc reference ## This is an AnythingLLM Architecture Issue The MCP servers work perfectly when executed directly - they're not the problem. The issue is **how AnythingLLM spawns child processes across different environments**: 1. **GUI applications** don't inherit shell environments properly 2. **Docker containers** lack proper PATH setup 3. **WSL processes** don't receive environment variables 4. **Cross-platform** path differences aren't handled ## Cost-Benefit Analysis **Current approach**: Dismissing each report individually as platform/tool-specific issues **Result**: Mounting reports, frustrated users, same root cause recurring **Proposed approach**: Address the underlying process spawning architecture once **Result**: Fix multiple platforms simultaneously, prevent future similar reports ## Simple Reproduction (Any Platform) I'd strongly encourage you to reproduce this on any platform: 1. Install Node.js via system package manager (not in standard PATH) 2. Configure any npx-based MCP server 3. Launch AnythingLLM via GUI/container → MCP fails with -32000 4. Launch AnythingLLM with proper environment → MCP works **This will take 5 minutes and demonstrate the cross-platform nature of the issue.** ## Proposed Solutions 1. **Fix process spawning**: Ensure proper environment inheritance across platforms 2. **Platform-aware PATH detection**: Auto-detect common installation paths per platform 3. **Better diagnostics**: Show actual vs expected environment when MCP startup fails 4. **Unified documentation**: Document the environment inheritance issue and workarounds Given that this affects **macOS, Linux, Docker, and Windows/WSL**, and that you're spending considerable time dismissing related reports, wouldn't it be more efficient to address the root architectural issue once rather than continue handling each platform manifestation separately? The workaround (shell wrappers) works across all platforms, proving this is a consistent process spawning issue within AnythingLLM, not platform-specific MCP problems. Would you be willing to reproduce this issue to see the cross-platform pattern? I believe fixing this systematically will prevent a significant number of future support requests. Thanks for your time and consideration.
yindo commented 2026-02-22 18:29:55 -05:00
Author
Owner
Copy Link
Copy Source

@PaoloC68 commented on GitHub (May 29, 2025):

@timothycarambat With #3909 lots of people will be happy!

@PaoloC68 commented on GitHub (May 29, 2025): @timothycarambat With #3909 **lots** of people will be happy!
yindo changed title from [BUG]: MCP Servers Fail to Start When Launched via GUI on macOS to [GH-ISSUE #3904] [BUG]: MCP Servers Fail to Start When Launched via GUI on macOS 2026-06-05 14:46:52 -04:00
Sign in to join this conversation.
No Branch/Tag Specified
Branches Tags
Labels
Clear labels
Desktop
Docker
Integration Request
Integration Request
OS: Linux
OS: Mobile
OS: Windows
UI/UX
blocked
bug
bug
core-team-only
documentation
duplicate
embed-widget
enhancement
feature request
github_actions
good first issue
investigating
needs info / can't replicate
possible bug
pull-request
Mirrored from GitHub Pull Request
 question
stage: specifications
wontfix
No Label possible bug
Milestone
No items
No Milestone
Projects
Clear projects
No project
Assignees
Clear assignees
yindo
No Assignees
1 Participants
Notifications
Due Date
No due date set.
Dependencies

No dependencies set.

Reference: Mintplex-Labs/anything-llm#2489
Delete Branch "%!s()"

Deleting a branch is permanent. Although the deleted branch may continue to exist for a short time before it actually gets removed, it CANNOT be undone in most cases. Continue?