第3章：环境搭建与工具准备

在学习MCP Server开发之前，我们需要先准备好开发环境。本章将详细介绍Node.js和Python两种开发环境的搭建，以及如何配置Claude Desktop来连接我们的MCP Server。

3.1 开发环境要求

MCP SDK目前支持两种主要开发语言：TypeScript和Python。你可以根据自己的偏好选择其中一种。

环境要求对比表

3.1.1 安装Node.js（TypeScript开发）

访问 nodejs.org 下载并安装Node.js。建议下载LTS（长期支持）版本。

安装完成后，在终端中验证安装：

# 检查Node.js版本
node --version
# 输出: v20.x.x 或更高

# 检查npm版本
npm --version
# 输出: 10.x.x 或更高

3.1.2 安装Python（Python开发）

访问 python.org 下载并安装Python 3.10或更高版本。

安装完成后验证：

# 检查Python版本
python --version
# 输出: Python 3.10.x 或更高

# 检查pip版本
pip --version

3.2 安装MCP SDK

MCP官方提供了两种语言的SDK，下面分别介绍安装方法。

3.2.1 TypeScript SDK安装

首先创建项目目录并初始化：

# 创建项目目录
mkdir my-mcp-server
cd my-mcp-server

# 初始化npm项目
npm init -y

# 安装MCP SDK
npm install @modelcontextprotocol/sdk

# 安装TypeScript（如需要）
npm install -D typescript @types/node

# 初始化TypeScript配置
npx tsc --init

3.2.2 Python SDK安装

Python安装更加简单：

# 创建项目目录
mkdir my-mcp-server
cd my-mcp-server

# 创建虚拟环境（推荐）
python -m venv venv

# Windows激活虚拟环境
venv\Scripts\activate

# macOS/Linux激活虚拟环境
source venv/bin/activate

# 安装MCP SDK
pip install mcp

3.3 Claude Desktop配置

Claude Desktop是Anthropic官方提供的桌面应用，支持MCP协议。我们需要配置它来连接开发的MCP Server。

3.3.1 下载安装Claude Desktop

访问 claude.ai/download 下载适合你操作系统的版本并安装。

3.3.2 配置文件位置

Claude Desktop使用JSON配置文件来管理MCP Server连接。不同操作系统的配置文件位置不同：

3.3.3 配置文件结构

claude_desktop_config.json 的基本结构如下：

{
  "mcpServers": {
    "server-name-1": {
      "command": "node",
      "args": ["/path/to/server1.js"]
    },
    "server-name-2": {
      "command": "python",
      "args": ["/path/to/server2.py"]
    }
  }
}

配置说明：

• mcpServers：包含所有MCP Server配置的对象
• server-name：Server的唯一标识名（自定义）
• command：启动Server的命令（node/python等）
• args：传递给命令的参数数组，通常是Server文件的路径

3.4 第一个MCP Server配置示例

让我们配置一个简单的天气查询Server作为示例。假设我们已经编写好了天气Server文件。

3.4.1 创建Server文件

首先，创建一个简单的Server文件（这里只是示例，实际代码在后续章节讲解）：

// weather-server.js
// 这是一个简单的示例文件

console.log("Weather server starting...");

3.4.2 配置Claude Desktop

编辑 claude_desktop_config.json 文件：

{
  "mcpServers": {
    "weather": {
      "command": "node",
      "args": ["C:/projects/my-mcp-server/weather-server.js"]
    }
  }
}

3.4.3 Python Server配置示例

如果是Python开发的Server：

{
  "mcpServers": {
    "weather": {
      "command": "python",
      "args": ["C:/projects/my-mcp-server/weather_server.py"]
    }
  }
}

3.4.4 使用虚拟环境的Python配置

如果使用了Python虚拟环境，需要指定虚拟环境中的Python解释器：

{
  "mcpServers": {
    "weather": {
      "command": "C:/projects/my-mcp-server/venv/Scripts/python.exe",
      "args": ["C:/projects/my-mcp-server/weather_server.py"]
    }
  }
}

3.5 开发工具推荐

好的开发工具能大幅提升开发效率。以下是推荐的工具组合：

3.5.1 代码编辑器

Visual Studio Code 是最推荐的编辑器，原因如下：

• 对TypeScript和Python都有出色的支持
• 内置调试功能
• 丰富的插件生态
• 内置终端，方便执行命令

推荐安装的VS Code插件：

3.5.2 热重载工具

开发时经常需要修改代码并重启Server，使用热重载工具可以自动完成这个过程。

TypeScript使用nodemon：

npm install -D nodemon ts-node

创建 nodemon.json 配置文件：

{
  "watch": ["src"],
  "ext": ".ts,.js",
  "ignore": [],
  "exec": "ts-node src/server.ts"
}

启动开发模式：

npx nodemon

Python使用watchdog（可选）：

pip install watchdog

3.6 调试技巧

调试是开发过程中不可避免的环节。下面介绍几种常用的MCP Server调试方法。

3.6.1 查看Claude Desktop日志

当MCP Server启动失败或运行异常时，Claude Desktop会记录错误日志。

日志文件位置：

3.6.2 使用stdio inspector

MCP官方提供了一个inspector工具，可以独立测试Server，无需启动Claude Desktop。

安装inspector：

npm install -g @modelcontextprotocol/inspector

使用inspector测试Server：

# TypeScript Server
npx @modelcontextprotocol/inspector node /path/to/server.js

# Python Server
npx @modelcontextprotocol/inspector python /path/to/server.py

Inspector会启动一个Web界面，可以在浏览器中查看和测试Server的所有功能。

3.6.3 日志级别设置

在Server代码中输出调试信息是最直接的调试方式。可以在Claude Desktop配置中设置环境变量来控制日志级别：

{
  "mcpServers": {
    "my-server": {
      "command": "node",
      "args": ["/path/to/server.js"],
      "env": {
        "DEBUG": "mcp:*",
        "LOG_LEVEL": "debug"
      }
    }
  }
}

3.7 测试环境验证

配置完成后，需要验证MCP Server是否被Claude Desktop正确加载。

3.7.1 查看Server列表

打开Claude Desktop，点击左下角的设置图标（⚙️），选择 Developer → MCP Servers：

• 如果配置正确，会看到你配置的Server名称
• 绿色圆点表示Server运行正常
• 红色圆点表示Server启动失败

3.7.2 测试Server功能

如果Server提供了工具（Tools），可以在Claude对话中测试：

用户：请列出所有可用的工具

Claude会回复当前可用的所有工具列表，包括MCP Server提供的工具。

3.7.3 验证脚本示例

也可以编写一个简单的验证脚本：

// test-connection.js
// 简单的测试脚本，验证SDK是否正确安装

import { Server } from '@modelcontextprotocol/sdk/server/index.js';

const server = new Server({
  name: 'test-server',
  version: '1.0.0'
}, {
  capabilities: { tools: {} }
});

console.log('✅ MCP SDK安装成功！');
console.log('Server实例创建成功');

运行测试：

node test-connection.js

3.8 常见问题排查

在环境搭建过程中，可能会遇到各种问题。下面列出常见问题及解决方法。

3.8.1 路径错误

解决方法：

1. 确认文件路径是否正确
2. Windows路径使用正斜杠 / 或双反斜杠 \\
3. 使用绝对路径而非相对路径
4. 检查文件是否存在且有读取权限

3.8.2 权限问题

解决方法：

1. macOS/Linux：使用 chmod +x 添加执行权限
2. Windows：以管理员身份运行Claude Desktop
3. 检查文件的所有者和权限设置

3.8.3 JSON格式错误

解决方法：

1. 使用JSON验证工具检查格式（如 jsonlint.com）
2. 确保所有字符串使用双引号
3. 检查是否有尾随逗号（最后一项后面不应该有逗号）
4. 确保花括号和方括号成对出现

3.8.4 依赖未安装

解决方法：

1. TypeScript：运行 npm install 安装依赖
2. Python：确认在正确的虚拟环境中，运行 pip install mcp
3. 检查Python是否使用了虚拟环境的解释器

3.8.5 端口冲突（SSE传输模式）

解决方法：

1. 更换Server监听的端口
2. 查找并关闭占用端口的进程
3. 使用动态端口分配

3.8.6 排查清单

遇到问题时，按以下顺序检查：

□ Node.js/Python版本是否符合要求
□ MCP SDK是否正确安装
□ 配置文件路径是否正确
□ JSON格式是否有效
□ 文件路径是否正确（绝对路径推荐）
□ 文件权限是否正确
□ 依赖包是否全部安装
□ 查看Claude Desktop日志获取详细错误信息
□ 使用inspector工具独立测试Server

本章小结

环境搭建完成后，我们就可以开始编写第一个MCP Server了！下一章将介绍MCP Server的基本结构和开发入门。