Skip to main content
已经知道 MCP 能做什么了，现在来把它真正跑起来。这篇覆盖 macOS 和 Windows 两个系统的完整配置命令，不省略任何一边——中文 MCP 教程最大的空白就是 Windows 用户照着 macOS 命令做必报错，这里把两套命令都给齐。配完之后用 MCP Inspector 验证服务正常，出错了去哪里找日志也一并说清楚。关于 MCP 能做哪些事情，可以先看 MCP 能做什么？10 个真实场景让 Claude / Cursor 变成超级助手。

​
前置环境：Node.js 安装

MCP Server 大多数是 Node.js 实现，先确认环境。

​
macOS

# 检查 Node.js 是否已安装
node -v
# 需要 >= 18，如果没有或版本低，用 Homebrew 安装
brew install node

# 验证 npm 和 npx 可用
npm -v
npx -v
如果没有 Homebrew： 
/bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"

​
Windows

Windows 上最常见的坑：npx 找不到命令，或者路径里有空格导致解析失败。 
# 在 PowerShell 里检查 Node.js
node -v
npm -v
npx -v
如果没有安装，从 nodejs.org 下载 Windows 安装包（选 LTS 版本），安装时勾选”Add to PATH”。 安装完成后重新打开一个新的 PowerShell 窗口，再运行上面的检查命令。很多人遇到”找不到命令”是因为没有重启 shell 让 PATH 生效。 如果遇到 PowerShell 执行策略报错： 
# 允许运行本地脚本（只需设置一次）
Set-ExecutionPolicy -Scope CurrentUser -ExecutionPolicy RemoteSigned

​
配置 Claude Desktop

​
macOS 配置文件路径与格式

配置文件位置： 
~/Library/Application Support/Claude/claude_desktop_config.json
如果文件不存在，手动创建： 
mkdir -p ~/Library/Application\ Support/Claude
touch ~/Library/Application\ Support/Claude/claude_desktop_config.json
以文件系统 MCP Server 为例，配置内容： 
{
  "mcpServers": {
    "filesystem": {
      "command": "npx",
      "args": [
        "-y",
        "@modelcontextprotocol/server-filesystem",
        "/Users/your-username/Documents"
      ]
    }
  }
}
/Users/your-username/Documents 替换成你想开放给 Claude 访问的目录路径。

​
Windows 配置文件路径与格式

配置文件位置： 
%APPDATA%\Claude\claude_desktop_config.json
在 PowerShell 里快速打开目录： 
explorer $env:APPDATA\Claude
如果 Claude 目录不存在，创建它： 
New-Item -ItemType Directory -Force -Path "$env:APPDATA\Claude"
New-Item -ItemType File -Force -Path "$env:APPDATA\Claude\claude_desktop_config.json"
Windows 上的配置文件内容，有两个关键差异：command 改用 cmd，npx 作为参数传入，目录路径用双反斜杠或正斜杠： 
{
  "mcpServers": {
    "filesystem": {
      "command": "cmd",
      "args": [
        "/c",
        "npx",
        "-y",
        "@modelcontextprotocol/server-filesystem",
        "C:/Users/your-username/Documents"
      ]
    }
  }
}
不能直接用 "command": "npx"，因为 Claude Desktop 在 Windows 上启动子进程时不经过 PowerShell 的 PATH 解析，必须显式通过 cmd /c 调用。 保存配置后完全退出 Claude Desktop（任务栏图标右键 → 退出），再重新打开——仅仅关窗口不生效，需要彻底退出进程。

​
配置 Cursor

​
Cursor 配置文件路径

Cursor 支持两级配置：
  • 项目级（仅当前项目生效）：项目根目录下 .cursor/mcp.json
  • 全局（所有项目生效）：~/.cursor/mcp.json（macOS/Linux）或 %USERPROFILE%\.cursor\mcp.json（Windows）

​
macOS / Linux

# 创建全局 MCP 配置文件
mkdir -p ~/.cursor
touch ~/.cursor/mcp.json
配置内容格式与 Claude Desktop 相同，使用 npx 命令： 
{
  "mcpServers": {
    "filesystem": {
      "command": "npx",
      "args": [
        "-y",
        "@modelcontextprotocol/server-filesystem",
        "/Users/your-username/Documents"
      ]
    }
  }
}

​
Windows

# 创建全局 MCP 配置目录
New-Item -ItemType Directory -Force -Path "$env:USERPROFILE\.cursor"
New-Item -ItemType File -Force -Path "$env:USERPROFILE\.cursor\mcp.json"
Windows 上 Cursor 对 npx 的处理比 Claude Desktop 好一些，可以直接用 npx： 
{
  "mcpServers": {
    "filesystem": {
      "command": "npx",
      "args": [
        "-y",
        "@modelcontextprotocol/server-filesystem",
        "C:/Users/your-username/Documents"
      ]
    }
  }
}
如果 Cursor 里 npx 仍然报找不到命令，改用绝对路径。先找到 npx 的实际路径： 
(Get-Command npx).Source
# 输出示例：C:\Program Files\nodejs\npx.cmd
然后在配置里用绝对路径： 
{
  "mcpServers": {
    "filesystem": {
      "command": "C:/Program Files/nodejs/npx.cmd",
      "args": [
        "-y",
        "@modelcontextprotocol/server-filesystem",
        "C:/Users/your-username/Documents"
      ]
    }
  }
}

​
用 MCP Inspector 验证服务是否跑通

配置完之后，先用 MCP Inspector 做验证，不要直接去客户端里试——出了问题不知道是 Server 的问题还是客户端的问题。 MCP Inspector 是官方提供的调试工具，可以在浏览器里直接调用 MCP Server 的工具，看请求和响应报文。

​
macOS / Linux

# 启动 MCP Inspector（无需安装，直接 npx 运行）
npx @modelcontextprotocol/inspector npx @modelcontextprotocol/server-filesystem /tmp/test-dir

# 替换最后的 Server 命令为你实际使用的 Server
# 格式：npx @modelcontextprotocol/inspector <server-command> [server-args...]

​
Windows

# Windows 上同样用 npx 运行
npx @modelcontextprotocol/inspector npx @modelcontextprotocol/server-filesystem C:/Users/your-username/Documents
命令执行后，终端会输出一个本地 URL（通常是 http://localhost:5173），在浏览器里打开。 Inspector 界面里：
  1. 左侧会显示已连接的 MCP Server 和它暴露的工具列表
  2. 点击任意工具，右侧可以填入参数并直接调用
  3. 下方会显示完整的 JSON-RPC 请求和响应报文

​
日志路径和报错排查

配置不生效或工具调用失败，先去找日志，别靠猜。

​
Claude Desktop 日志路径

macOS： 
# MCP 相关日志
ls ~/Library/Logs/Claude/mcp*.log

# 查看最新的 MCP 日志（实时跟踪）
tail -f ~/Library/Logs/Claude/mcp-server-filesystem.log
# 文件名格式：mcp-server-{server-name}.log
Windows： 
# 日志目录
dir $env:APPDATA\Claude\logs\

# 实时查看日志（PowerShell）
Get-Content "$env:APPDATA\Claude\logs\mcp-server-filesystem.log" -Wait -Tail 50

​
高频报错解法

报错信息： Error: spawn npx ENOENT原因： Claude Desktop 找不到 npx 命令，PATH 没有传递进来。macOS 解法——在配置文件里用绝对路径：
# 找到 npx 实际路径
which npx
# 输出示例：/usr/local/bin/npx 或 /opt/homebrew/bin/npx
然后配置改为：
{
  "mcpServers": {
    "filesystem": {
      "command": "/opt/homebrew/bin/npx",
      "args": ["-y", "@modelcontextprotocol/server-filesystem", "/tmp"]
    }
  }
}
Windows 解法：改用 cmd /c npx（见上文 Windows 配置部分）。
报错信息： Error: connect ECONNREFUSED 127.0.0.1:PORT原因： Server 进程没有成功启动，或者端口被占用（多见于 SSE/HTTP transport）。排查步骤：
# macOS/Linux：查看是否有进程监听对应端口
lsof -i :3000
# 没有输出说明 Server 没跑起来

# 手动启动 Server 看报错信息
npx @modelcontextprotocol/server-filesystem /tmp
# 直接看终端输出的错误原因

# Windows：查看端口占用
netstat -ano | findstr :3000
报错信息： MCP error -32001: Request timed out原因： Server 处理时间超过客户端默认超时（通常 30 秒）。常见于 Server 内部调用外部 API 响应慢，或者 Server 启动时需要下载依赖。首次运行时 npx -y 会自动下载 npm 包，可能需要 30-60 秒，超过客户端超时就会报这个错。解法：先手动跑一次让缓存下来。
# 手动预热，让 npx 完成下载
npx -y @modelcontextprotocol/server-filesystem /tmp
# 看到 "MCP server running" 或类似提示后 Ctrl+C，再去配置客户端

​
验证配置是否生效

MCP Inspector 确认通了之后，重启客户端，检查工具是否出现。 Claude Desktop：重启后，在对话框左下角会出现一个锤子图标，点击可以看到已加载的工具列表。如果图标没有出现，说明 Server 没有成功加载，回去查日志。 Cursor：在 Cursor 的 Settings → MCP 里可以看到已注册的 Server 状态（绿点=正常，红点=连接失败）。 
# 用 curl 直接测试 MCP Server 的 JSON-RPC 接口是否响应（stdio Server 不适用此方法）
# 以 HTTP transport 的 Server 为例
curl -s -X POST http://localhost:3000/mcp \
  -H "Content-Type: application/json" \
  -d '{"jsonrpc":"2.0","method":"initialize","params":{"protocolVersion":"2024-11-05","capabilities":{},"clientInfo":{"name":"test","version":"1.0"}},"id":1}' \
  | python3 -m json.tool
本地 stdio Server 跑通之后，如果你需要在多台设备上共享同一个 MCP Server，或者让 Server 7×24 在线，就需要考虑云端部署了。本地 MCP vs 云端 MCP：什么时候必须上 VPS？列出了 5 个必须上云的场景，帮你做决策。

​
常见问题

在 %APPDATA%\Claude\logs\ 目录下，文件名格式是 mcp-server-{server-name}.log。用 PowerShell 实时查看：Get-Content "$env:APPDATA\Claude\logs\mcp-server-filesystem.log" -Wait -Tail 50。
Claude Desktop 需要完全退出后再重启才能读取新配置，仅关闭窗口不够——右键任务栏图标选”退出”，或在 macOS 上用 Cmd+Q。Cursor 同理，改完配置需要重启整个应用。
Inspector 默认使用 5173 端口，如果被占用可以通过环境变量指定其他端口：
PORT=5174 npx @modelcontextprotocol/inspector npx @modelcontextprotocol/server-filesystem /tmp
可以。在配置文件里加多个 key 即可，每个 Server 独立启动和管理：
{
  "mcpServers": {
    "filesystem": { "command": "npx", "args": ["..."] },
    "github": { "command": "npx", "args": ["..."] },
    "postgres": { "command": "npx", "args": ["..."] }
  }
}
本文最后更新于 2026-03，测试环境：macOS 15.3 / Windows 11 24H2，Node.js 22 LTS，Claude Desktop 0.9.x，Cursor 0.48.x，MCP Inspector 0.9.0。工具版本迭代较快，建议每 3 个月检查一次配置格式变更。