# Claude Desktop 配置指南
本指南将帮助你将这个 MCP Hello World 服务器添加到 Claude Desktop。
## 前置条件
✅ Python 3.11+ 已安装
✅ 依赖包已安装（`pip install -r requirements.txt`）
✅ Claude Desktop 已安装
## 配置步骤
### 1. 找到 Claude Desktop 配置文件位置
Claude Desktop 的配置文件位置取决于你的操作系统：
**Windows:**
```
%APPDATA%\Claude\claude_desktop_config.json
```
完整路径通常是：
```
C:\Users\<你的用户名>\AppData\Roaming\Claude\claude_desktop_config.json
```
**macOS:**
```
~/Library/Application Support/Claude/claude_desktop_config.json
```
**Linux:**
```
~/.config/Claude/claude_desktop_config.json
```
### 2. 编辑配置文件
#### 方法一：如果配置文件不存在
1. 创建配置文件目录（如果不存在）
2. 创建 `claude_desktop_config.json` 文件
3. 复制以下内容：
```json
{
"mcpServers": {
"hello-world": {
"command": "python",
"args": [
"C:\\work\\backend\\python-mcp\\mcp_server.py"
],
"cwd": "C:\\work\\backend\\python-mcp"
}
}
}
```
**重要：** 将路径 `C:\\work\\backend\\python-mcp` 替换为你的实际项目路径！
#### 方法二：如果配置文件已存在
1. 打开现有的 `claude_desktop_config.json`
2. 在 `mcpServers` 对象中添加新的服务器配置：
```json
{
"mcpServers": {
"existing-server": {
// ... 现有配置 ...
},
"hello-world": {
"command": "python",
"args": [
"C:\\work\\backend\\python-mcp\\mcp_server.py"
],
"cwd": "C:\\work\\backend\\python-mcp"
}
}
}
```
### 3. 路径配置说明
#### Windows 路径格式
使用双反斜杠或正斜杠：
```json
"C:\\work\\backend\\python-mcp\\mcp_server.py" // 双反斜杠
// 或
"C:/work/backend/python-mcp/mcp_server.py" // 正斜杠
```
#### 使用虚拟环境（推荐）
如果你使用虚拟环境，指定 Python 解释器的完整路径：
```json
{
"mcpServers": {
"hello-world": {
"command": "C:\\work\\backend\\python-mcp\\venv\\Scripts\\python.exe",
"args": [
"C:\\work\\backend\\python-mcp\\mcp_server.py"
],
"cwd": "C:\\work\\backend\\python-mcp"
}
}
}
```
#### 使用相对路径（如果可能）
```json
{
"mcpServers": {
"hello-world": {
"command": "python",
"args": [
"mcp_server.py"
],
"cwd": "C:\\work\\backend\\python-mcp"
}
}
}
```
### 4. 验证配置
#### 检查 JSON 格式
确保 JSON 格式正确，可以使用在线 JSON 验证器或 Python：
```bash
python -c "import json; json.load(open('claude_desktop_config.json'))"
```
#### 测试服务器
在配置之前，先测试服务器是否能正常运行：
```bash
cd C:\work\backend\python-mcp
python mcp_server.py
```
如果程序启动后没有报错（stdio模式会等待输入），说明代码正常。
### 5. 重启 Claude Desktop
1. **完全退出 Claude Desktop**
- 确保所有窗口都已关闭
- 检查任务管理器/活动监视器，确保没有残留进程
2. **重新启动 Claude Desktop**
3. **验证连接**
- 打开 Claude Desktop
- 在聊天界面，你应该能看到 MCP 工具可用
- 尝试使用：`使用hello_world工具问候张三`
### 6. 故障排除
#### 问题1: Claude Desktop 无法启动 MCP 服务器
**检查清单：**
- [ ] 配置文件路径是否正确
- [ ] JSON 格式是否正确（无语法错误）
- [ ] Python 路径是否正确
- [ ] 项目文件路径是否存在
- [ ] 依赖是否已安装
**调试方法：**
1. 查看 Claude Desktop 的日志文件
2. 手动运行服务器测试：
```bash
python C:\work\backend\python-mcp\mcp_server.py
```
#### 问题2: 工具不可用
**可能原因：**
- MCP 服务器未成功连接
- 需要重启 Claude Desktop
- 检查 Claude Desktop 的 MCP 连接状态
#### 问题3: 路径问题
**Windows 路径转义：**
```json
// 错误
"C:\work\backend\python-mcp\mcp_server.py"
// 正确（双反斜杠）
"C:\\work\\backend\\python-mcp\\mcp_server.py"
// 正确（正斜杠）
"C:/work/backend/python-mcp/mcp_server.py"
```
### 7. 完整配置示例
```json
{
"mcpServers": {
"hello-world": {
"command": "python",
"args": [
"C:\\work\\backend\\python-mcp\\mcp_server.py"
],
"cwd": "C:\\work\\backend\\python-mcp",
"env": {
"PYTHONPATH": "C:\\work\\backend\\python-mcp"
}
}
}
}
```
### 8. 使用工具
配置成功后，在 Claude Desktop 中：
1. **直接使用：**
```
使用hello_world工具问候Alice，用英文，重复3次
```
2. **查看可用工具：**
Claude Desktop 应该会自动显示可用的 MCP 工具
3. **工具参数：**
- `name`: 要问候的名字（默认: "World"）
- `language`: 语言，zh 或 en（默认: "zh"）
- `count`: 重复次数，1-10（默认: 1）
## 快速配置脚本
你也可以使用 PowerShell 快速创建配置：
```powershell
$configPath = "$env:APPDATA\Claude\claude_desktop_config.json"
$configDir = Split-Path $configPath
# 创建目录
if (-not (Test-Path $configDir)) {
New-Item -ItemType Directory -Path $configDir -Force
}
# 配置内容
$config = @{
mcpServers = @{
"hello-world" = @{
command = "python"
args = @("C:\work\backend\python-mcp\mcp_server.py")
cwd = "C:\work\backend\python-mcp"
}
}
} | ConvertTo-Json -Depth 10
# 写入文件
$config | Out-File -FilePath $configPath -Encoding UTF8
Write-Host "配置文件已创建: $configPath"
Write-Host "请修改路径为你的实际项目路径！"
```
## 参考
- [Claude Desktop MCP 文档](https://claude.ai/docs/mcp)
- [MCP 协议规范](https://modelcontextprotocol.io)
