本文详细介绍了 MCP 服务在安装和运行过程中遇到的异常情况，并提供了相应的解决方案和排查步骤，包括处理缺少命令环境、服务初始化失败及配置错误等问题。
服务添加或安装异常 1. 缺少 npx 命令所需环境
异常信息：failed to start command: exec: "npx": executable file not found in $PATH
解决方案： 下载并安装 Node.js。
Node.js 版本须在 v18 及以上，npm 版本须在 v8 及以上。版本过低可能导致工具调用失败
您可以访问 Node.js 官网 ，下载并安装 Node.js 18 或更高版本，也可以选择通过以下方式完成：
安装验证步骤
1.下载并安装，使用 nvm-windows 管理多版本： nvm install 22.14 . 0 # 安装指定版本 nvm use 22.14 . 0
2.安装完成后，在终端中运行以下命令确认是否安装成功。 3.安装成功后，终端将显示已安装的 Node.js 版本号。 下载并安装，使用 brew 安装（需先安装 brew ）。
# 1. 更新并安装brew brew update brew install node # 2. 验证核心工具链 echo "Node.js版本: $( node -v )" echo "npm版本: $( npm -v )" echo "npx版本: $( npx -v )" # 3. 配置环境变量（必要时） echo 'export PATH="/usr/local/opt/node@16/bin:$PATH"' >> ~/.zshrc
2. 缺少 uvx 命令所需环境
异常信息：failed to start command: exec: "uvx": executable file not found in $PATH
解决方案： 安装 uv， uvx 是 uv 提供的命令行工具，用于快速运行 Python 脚本。
您可以前往 Python 官网 ，下载并安装 Python 3.8 或更高版本，也可以选择通过以下方式完成：
安装验证步骤
1.下载并安装
Windows 使用下面命令安装 powershell - ExecutionPolicy ByPass - c "irm https://astral.sh/uv/install.ps1 | iex"
macOS 和 Linux 使用下面命令安装 curl -LsSf https://astral.sh/uv/install.sh | sh
2.安装完成后，在终端中运行以下命令确认是否安装成功。
3.安装成功后，终端将显示已安装的 uv 版本号。
3. 无法初始化 MCP Client
异常信息：failed to initialize MCP client: context deadline exceeded
异常原因，包括但不限于以下原因：
服务参数配置错误 ：MCP 服务的参数设置可能存在错误或其他情况，影响服务初始化。资源拉取失败 ：由于网络问题，无法成功拉取资源导致的安装失败。网络安全限制 ：由于公司内部安全组件的拦截，导致 MCP 服务初始化异常。
排查步骤：
1. 单击复制完整命令，可以获取完整的命令。
2. 在终端中运行该命令，可以获取详细异常信息。
3.分析异常信息，进行对应修复。
常见问题 1：配置错误
在以上异常示例中，通过异常信息可以看出，是由于 Redis 连接URL 配置错误导致连接失败，据此应检查并通过编辑该MCP服务，修正错误的URL配置。
常见问题2：资源拉取失败
如果由于资源拉取问题导致命令运行失败，可以在命令行中执行以下命令，添加镜像源，再重启 lingma 进程后再试。
npm config set registry https://registry.npmmirror.com
export UV_INDEX_URL=https://mirrors.aliyun.com/pypi/simple/
常见问题3：Node.js 运行被安全组件拦截
根据安全组件的拦截提示，对Node.js进程或相关执行文件进行授权或加白操作。
工具使用相关问题 如果您在使用 MCP 广场中的服务存在问题，请联系魔搭社区，获取技术支持。 ModelScope 开发者群（钉钉群号 44837352）
1. 环境变量或参数填写错误，导致工具执行失败 如果 MCP 工具调用出现异常或返回结果不符合预期，建议您首先展开工具调用详情，查看具体的错误信息，并据此进行分析与排查。部分 MCP 服务（如 Mastergo 和 Figma）的 API_KEY 或 TOKEN 等关键认证信息包含在“参数（args）”中。 进入我的服务 页面。 找到对应 MCP 服务，单击编辑。 在服务配置中，查看参数（args） 部分。 替换其中需要更新或填写的变量内容，确保其准确无误，重新连接服务后再尝试调用。
2. 模型无法正常调用 MCP 工具
确认当前在智能体 模式 。
如果未打开相关工程目录，系统将仅进入智能问答模式 ，无法调用 MCP 工具。请先加载对应的工程目录，并切换到智能体 模式。
确认 MCP 服务处于已连接状态 ：
如果服务连接中断，在界面右侧单击，系统会自动尝试重新启动 MCP 服务。
使用建议： 避免MCP服务及其工具使用相似命名（如 TextAnalyzer-Pro 和 TextAnalyzer-Plus 都包含名为 fetchText 的工具且功能类似），防止模型调用时产生歧义。
3. 个人设置、MCP 工具页无法打开，会话面板显示空白。 当页面显示空白并在 idea.log 中有如下报错信息：“WARN - #c.i.u.j.JBCefApp - JCefAppConfig.class is not from a JBR module”。
异常原因： Android Studio 默认设置不支持 JCEF，导致无法加载个人设置、MCP 等页面。解决方案：
配置 JCEF：在 IDE 中选择Help Find Action.. ，在弹出的输入框中输入 "Registry" 并打开。 配置 IDE Runtime：再次选择Help Find Action.. ，在输入框中输入 "Choose Boot Runtime for the IDE" 并打开，选择较新的 JCEF Runtime 版本，然后确定。 重启 IDE。
4. MCP 服务列表无法正常加载 服务列表持续显示加载中。
重新启动 IDE。
如果问题仍未解决，可尝试手动启动 Qoder CN 服务：
Windows 系统
进入目录：.lingma/bin/x.x.x/CPU架构_64_系统/
执行命令：
Mac 系统
单击电脑左上角苹果图标，选择“关于本机”查看处理器型号，然后根据处理器型号进入对应的目录。
m1 芯片：/.lingma/bin/x.x.x/aarch64_darwin/Qoder CN
intel 芯片：/.lingma/bin/x.x.x/x86_64_darwin/Qoder CN
执行命令：
等待启动成功后，重新单击登录按钮。
