---

name: configure-mcp-server description: > 为 Claude Code 和 Claude Desktop 配置 MCP（Model Context Protocol） 服务器。涵盖 mcptools 设置、Hugging Face 集成、WSL 路径处理和多客户端 配置。适用于设置 Claude Code 通过 mcptools 连接 R、为 Claude Desktop 配置 MCP 服务器、添加 Hugging Face 或其他远程 MCP 服务器，或排查 客户端与服务器之间的 MCP 连接问题。 license: MIT allowed-tools: Read Write Edit Bash Grep Glob metadata: author: Philipp Thoss version: "1.0" domain: mcp-integration complexity: intermediate language: multi tags: mcp, claude-code, claude-desktop, mcptools, configuration locale: zh-CN source_locale: en source_commit: 6f65f316 translator: claude-sonnet-4-6 translation_date: 2026-03-16

配置 MCP 服务器

为 Claude Code（WSL）和 Claude Desktop（Windows）设置 MCP 服务器连接。

适用场景

• 设置 Claude Code 通过 mcptools 连接 R
• 为 Claude Desktop 配置 MCP 服务器
• 添加 Hugging Face 或其他远程 MCP 服务器
• 排查工具之间的 MCP 连接问题

输入

• 必需：MCP 服务器类型（mcptools、Hugging Face、自定义）
• 必需：客户端（Claude Code、Claude Desktop 或两者）
• 可选：认证令牌
• 可选：自定义服务器实现

步骤

第 1 步：安装 MCP 服务器包

R（mcptools）：

install.packages("remotes")
remotes::install_github("posit-dev/mcptools")

Hugging Face：

npm install -g mcp-remote

预期结果： mcptools 从 GitHub 安装并在 R 中无错误加载。mcp-remote 可通过 which mcp-remote 或 npm list -g mcp-remote 全局访问。

失败处理： 对于 mcptools，确保先安装 remotes。如果 GitHub 限制安装速率，在 ~/.Renviron 中设置 GITHUB_PAT。对于 mcp-remote，验证 Node.js 和 npm 已安装并在 PATH 中。

第 2 步：配置 Claude Code（WSL）

R mcptools 服务器：

claude mcp add r-mcptools stdio \
  "/mnt/c/Program Files/R/R-4.5.0/bin/Rscript.exe" \
  -- -e "mcptools::mcp_server()"

Hugging Face 服务器：

claude mcp add hf-mcp-server \
  -e HF_TOKEN=your_token_here \
  -- mcp-remote https://huggingface.co/mcp

验证配置：

claude mcp list
claude mcp get r-mcptools

预期结果： claude mcp list 显示 r-mcptools 和 hf-mcp-server（或已添加的服务器）。claude mcp get r-mcptools 显示正确的命令和参数。

失败处理： 如果服务器未出现在列表中，验证 ~/.claude.json 包含正确的条目。如果找不到 claude 命令，添加到 PATH：export PATH="$HOME/.claude/local/node_modules/.bin:$PATH"。

第 3 步：配置 Claude Desktop（Windows）

编辑 %APPDATA%\Claude\claude_desktop_config.json：

{
  "mcpServers": {
    "r-mcptools": {
      "command": "C:\\PROGRA~1\\R\\R-45~1.0\\bin\\x64\\Rscript.exe",
      "args": ["-e", "mcptools::mcp_server()"]
    },
    "hf-mcp-server": {
      "command": "mcp-remote",
      "args": ["https://huggingface.co/mcp"],
      "env": {
        "HF_TOKEN": "your_token_here"
      }
    }
  }
}

重要：对包含空格的 Windows 目录使用 8.3 短路径（PROGRA~1 而非 Program Files）。使用环境变量传递令牌，不要用 --header 参数。

预期结果： %APPDATA%\Claude\claude_desktop_config.json 中的 JSON 配置文件有效，包含正确的服务器条目。Claude Desktop 重启后显示 MCP 服务器指示器。

失败处理： 使用 linter 验证 JSON（如 jq . < config.json）。如果 Windows 路径空格导致解析错误，使用 8.3 短路径（PROGRA~1）。确保 Claude Desktop 完全重启（不仅是最小化）。

第 4 步：为 MCP 配置 R 会话

在项目 .Rprofile 中添加：

if (requireNamespace("mcptools", quietly = TRUE)) {
  mcptools::mcp_session()
}

这会在 RStudio 中打开项目时自动启动 MCP 会话。

预期结果： .Rprofile 文件在 RStudio 中打开项目时条件性启动 mcptools::mcp_session()，自动提供 MCP 工具。

失败处理： 如果会话启动时找不到 mcptools，验证它安装在 RStudio 使用的库中（检查 .libPaths()）。如果使用 renv，确保 mcptools 在 renv 库中。

第 5 步：验证连接

从 WSL 测试 R MCP：

"/mnt/c/Program Files/R/R-4.5.0/bin/Rscript.exe" -e "mcptools::mcp_server()"

从 Claude Code 内测试：

启动 Claude Code 并使用 MCP 工具 -- 它们应出现在工具列表中。

测试 Claude Desktop：

配置更改后重启 Claude Desktop。检查 UI 中的 MCP 服务器指示器。

预期结果： 运行带有 mcptools::mcp_server() 的 Rscript 产生无错误输出。活动会话期间 MCP 工具出现在 Claude Code 工具列表中。重启后 Claude Desktop 显示服务器状态。

失败处理： 如果 Rscript 命令失败，检查完整路径是否正确（使用 ls "/mnt/c/Program Files/R/" 验证 R 版本）。如果工具未出现在 Claude Code 中，重启会话。对于 Claude Desktop，检查防火墙设置。

第 6 步：多服务器配置

Claude Code 和 Claude Desktop 均支持同时使用多个 MCP 服务器：

# Claude Code: add multiple servers
claude mcp add r-mcptools stdio "/path/to/Rscript.exe" -- -e "mcptools::mcp_server()"
claude mcp add hf-mcp-server -e HF_TOKEN=token -- mcp-remote https://huggingface.co/mcp
claude mcp add custom-server stdio "/path/to/server" -- --port 3001

预期结果： 多个 MCP 服务器同时配置且可访问。claude mcp list 显示所有服务器。每个服务器的工具在同一 Claude Code 会话中可用。

失败处理： 如果服务器冲突，检查配置中每个服务器名称是否唯一。如果一个服务器阻塞其他服务器，验证服务器使用非阻塞 I/O（stdio 传输自动处理）。

验证清单

• claude mcp list 显示所有已配置的服务器
• R MCP 服务器响应工具调用
• Hugging Face MCP 服务器认证并响应
• Claude Code 和 Claude Desktop 均可连接（如两者都已配置）
• 会话期间 MCP 工具出现在工具列表中

常见问题

• Windows 路径空格：使用 8.3 短名称或正确引用路径。不同工具解析路径的方式不同。
• 命令参数中的令牌：在 Windows 上，--header "Authorization: Bearer token" 由于解析问题而失败。改用环境变量。
• 混淆 Claude Code 和 Claude Desktop 配置：这是不同的工具，有不同的配置文件（~/.claude.json 与 %APPDATA%\Claude\）
• npx 与全局安装：npx mcp-remote 在 Claude Desktop 上下文中可能失败。使用 npm install -g mcp-remote 全局安装。
• mcptools 版本：确保 mcptools 是最新版本。它需要 ellmer 包作为依赖。

相关技能

• build-custom-mcp-server - 创建自定义 MCP 服务器
• troubleshoot-mcp-connection - 调试连接问题
• setup-wsl-dev-environment - WSL 设置前提