MCP工具实战使用指南

文档说明：详细解答MCP工具的配置、下载、使用等实际操作问题。

📍 一、MCP配置文件位置

Q1: MCP只需要在项目根目录的.mcp.json中定义就可以了吗？

答案：❌ 不完全正确

正确的配置位置

MCP配置文件有两个可能的位置：

位置1：全局配置（推荐）⭐

复制代码

~/.config/claude-code/mcp.json          # Linux/Mac
%APPDATA%\claude-code\mcp.json          # Windows

特点：

✅ 所有项目共享
✅ 一次配置，到处可用
✅ Claude Code官方推荐位置

位置2：项目配置

复制代码

/your-project/.mcp.json                 # 项目根目录

特点：

✅ 项目特定配置
✅ 可以覆盖全局配置
✅ 适合项目专用工具

配置优先级

复制代码

项目配置 (.mcp.json) > 全局配置 (~/.config/claude-code/mcp.json)

示例：

全局配置了context7、open-websearch
项目配置了serena（项目专用）
结果：项目中可以使用所有3个工具

📥 二、MCP工具下载位置

Q2: MCP工具会下载到哪？

答案：取决于MCP服务器的类型

类型1：npm包（通过npx启动）

配置示例：

json 复制代码

{
  "context7": {
    "type": "stdio",
    "command": "npx",
    "args": ["-y", "@upstash/context7-mcp@latest"]
  }
}

下载位置：

复制代码

~/.npm/_npx/                            # npx缓存目录
或
/tmp/npx-xxxxx/                         # 临时目录

特点：

✅ 自动下载和管理
✅ 使用@latest总是获取最新版本
✅ 不需要手动安装
⚠️ 首次启动会下载（需要网络）

查看下载的包：

bash 复制代码

# 查看npx缓存
ls ~/.npm/_npx/

# 手动安装到全局（可选）
npm install -g @upstash/context7-mcp

类型2：本地项目（Python/Node.js）

配置示例：

json 复制代码

{
  "serena": {
    "type": "stdio",
    "command": "python",
    "args": ["/home/cbx/code/serena/mcp_server.py"]
  }
}

位置：

复制代码

/home/cbx/code/serena/                  # 你指定的本地路径

特点：

✅ 完全控制代码
✅ 可以自定义功能
⚠️ 需要手动维护

类型3：全局命令

配置示例：

json 复制代码

{
  "codex": {
    "type": "stdio",
    "command": "codex",
    "args": ["mcp-server"]
  }
}

位置：

复制代码

/usr/local/bin/codex                    # 系统PATH中
或
~/.local/bin/codex                      # 用户bin目录

特点：

✅ 系统级安装
⚠️ 需要手动安装命令

🚀 三、MCP工具的使用方式

Q3: 怎么使用？需要命令触发吗？

答案：✅ Claude Code会自动使用，不需要手动命令

自动化流程

复制代码

1. Claude Code启动
   ↓
2. 读取.mcp.json配置
   ↓
3. 自动启动所有MCP服务器
   ↓
4. 建立连接（stdio通信）
   ↓
5. AI可以直接调用工具
   ↓
6. 用户无需手动触发

实际使用示例

场景1：使用Context7查询文档

用户提问：

复制代码

"如何使用React Hooks？"

Claude的内部流程：

复制代码

1. 识别需要查询文档
2. 自动调用context7 MCP工具
3. 查询React文档
4. 返回结果给用户

用户体验：

✅ 无需输入特殊命令
✅ AI自动判断何时使用工具
✅ 结果直接呈现

场景2：使用open-websearch搜索

用户提问：

复制代码

"2025年最新的AI技术趋势是什么？"

Claude的内部流程：

复制代码

1. 识别需要最新信息
2. 自动调用open-websearch MCP工具
3. 搜索网页
4. 整合结果返回

用户体验：

✅ 自动联网搜索
✅ 无需手动触发
✅ 结果包含来源链接

场景3：使用Playwright控制浏览器

用户提问：

复制代码

"帮我测试登录页面是否正常"

Claude的内部流程：

复制代码

1. 识别需要浏览器操作
2. 自动调用Playwright MCP工具
3. 打开浏览器
4. 执行测试操作
5. 返回测试结果

用户体验：

✅ 自动化浏览器操作
✅ 无需写测试脚本
✅ 实时反馈结果

🤖 四、Claude Code的自动使用机制

Q4: Claude Code会自动使用吗？

答案：✅ 是的，完全自动

自动使用的条件

条件1：MCP服务器已启动

复制代码

Claude Code启动时自动启动所有配置的MCP服务器

条件2：AI判断需要使用工具

复制代码

基于用户问题，AI自动决定是否调用MCP工具

条件3：工具可用

复制代码

MCP服务器正常运行，连接正常

自动使用的流程

需要文档
需要搜索
需要浏览器
不需要工具
用户提问
AI分析问题
调用context7
调用open-websearch
调用Playwright
直接回答
返回结果

用户无需做什么

❌ 不需要：

输入特殊命令（如/search、/docs）
手动启动MCP服务器
指定使用哪个工具

✅ 只需要：

正常提问
AI自动判断和使用工具

🔧 五、完整配置示例

示例1：最小配置（使用npm包）

文件位置 ：~/.config/claude-code/mcp.json

json 复制代码

{
  "mcpServers": {
    "context7": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "@upstash/context7-mcp@latest"],
      "env": {}
    }
  }
}

使用：

保存配置文件
重启Claude Code
直接提问："如何使用Vue 3？"
AI自动调用context7查询文档

示例2：多工具配置

文件位置 ：/your-project/.mcp.json

json 复制代码

{
  "mcpServers": {
    "context7": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "@upstash/context7-mcp@latest"],
      "env": {}
    },
    "open-websearch": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "open-websearch@latest"],
      "env": {
        "DEFAULT_SEARCH_ENGINE": "duckduckgo"
      }
    },
    "playwright": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "@playwright/mcp@latest"],
      "env": {}
    }
  }
}

使用：

在项目根目录创建.mcp.json
重启Claude Code
提问时AI会自动选择合适的工具

示例3：自定义工具配置

文件位置 ：~/.config/claude-code/mcp.json

json 复制代码

{
  "mcpServers": {
    "my-database": {
      "type": "stdio",
      "command": "python",
      "args": ["/home/user/mcp-tools/database_server.py"],
      "env": {
        "DB_HOST": "localhost",
        "DB_PORT": "5432",
        "DB_NAME": "mydb"
      }
    }
  }
}

前提：

已开发database_server.py
实现了MCP协议

使用：

保存配置
重启Claude Code
提问："查询用户表的数据"
AI自动调用自定义数据库工具

🐛 六、常见问题排查

问题1：MCP工具没有自动使用

可能原因：

❌ MCP服务器启动失败
❌ 配置文件路径错误
❌ AI判断不需要使用工具

排查步骤：

bash 复制代码

# 1. 检查配置文件是否存在
ls ~/.config/claude-code/mcp.json
ls .mcp.json

# 2. 验证JSON格式
cat ~/.config/claude-code/mcp.json | jq .

# 3. 手动测试MCP服务器
npx -y @upstash/context7-mcp@latest

# 4. 查看Claude Code日志
# 启动时会显示MCP连接状态

解决方法：

确保配置文件格式正确
重启Claude Code
检查网络连接（npm包需要下载）

问题2：首次启动很慢

原因：

npx需要下载npm包
网络速度影响

解决方法：

bash 复制代码

# 方法1：预先安装到全局
npm install -g @upstash/context7-mcp
npm install -g open-websearch
npm install -g @playwright/mcp

# 方法2：使用国内镜像
npm config set registry https://registry.npmmirror.com

# 方法3：等待首次下载完成（只需一次）

问题3：MCP工具调用失败

可能原因：

❌ 环境变量缺失（如API_KEY）
❌ 权限问题
❌ 依赖缺失

排查步骤：

bash 复制代码

# 1. 检查环境变量
echo $API_KEY

# 2. 检查Python/Node.js版本
python --version
node --version

# 3. 检查依赖
pip list | grep mcp
npm list -g | grep mcp

解决方法：

在.mcp.json的env中设置环境变量
安装必要的依赖
检查文件权限

📊 七、MCP工具使用对比

手动命令 vs 自动使用

特性	手动命令	MCP自动使用
触发方式	输入`/command`	AI自动判断
用户体验	需要记住命令	自然对话
灵活性	固定命令	智能选择
学习成本	需要学习命令	零学习成本
适用场景	明确操作	所有场景

示例对比

手动命令方式（假设）：

复制代码

用户：/search "React Hooks"
AI：搜索中...
AI：返回结果

MCP自动方式（实际）：

复制代码

用户：React Hooks怎么用？
AI：（自动调用context7）让我查询最新文档...
AI：React Hooks是...（返回详细说明）

结论：MCP自动使用更自然、更智能

🎯 八、最佳实践

1. 配置文件管理

推荐结构：

复制代码

~/.config/claude-code/
├── mcp.json                    # 全局通用工具
└── projects/
    └── dmv/
        └── .mcp.json           # 项目专用工具

全局配置（通用工具）：

json 复制代码

{
  "mcpServers": {
    "context7": {...},
    "open-websearch": {...},
    "playwright": {...}
  }
}

项目配置（专用工具）：

json 复制代码

{
  "mcpServers": {
    "project-database": {...},
    "project-api": {...}
  }
}

2. 环境变量管理

不要硬编码敏感信息：

❌ 错误做法：

json 复制代码

{
  "env": {
    "API_KEY": "sk-1234567890abcdef"
  }
}

✅ 正确做法：

json 复制代码

{
  "env": {
    "API_KEY": "${API_KEY}"
  }
}

在系统中设置环境变量：

bash 复制代码

# Linux/Mac
export API_KEY="sk-1234567890abcdef"

# Windows
set API_KEY=sk-1234567890abcdef

3. 版本管理

使用固定版本（生产环境）：

json 复制代码

{
  "args": ["-y", "@upstash/context7-mcp@1.2.3"]
}

使用最新版本（开发环境）：

json 复制代码

{
  "args": ["-y", "@upstash/context7-mcp@latest"]
}

4. 性能优化

减少启动时间：

bash 复制代码

# 预先安装常用工具
npm install -g @upstash/context7-mcp
npm install -g open-websearch
npm install -g @playwright/mcp

配置使用全局安装：

json 复制代码

{
  "command": "context7-mcp",
  "args": []
}

🎉 九、总结

核心要点

Q1: 只需要在.mcp.json中定义就可以了吗？

A: ✅ 是的，但有两个位置：

全局：~/.config/claude-code/mcp.json
项目：/project/.mcp.json

Q2: MCP工具会下载到哪？

A: 取决于类型：

npm包：~/.npm/_npx/（自动管理）
本地项目：你指定的路径
全局命令：系统PATH中

Q3: 怎么使用？需要命令触发吗？

A: ❌ 不需要命令

AI自动判断何时使用
用户只需正常提问
完全透明的体验

Q4: Claude Code会自动使用吗？

A: ✅ 完全自动

启动时自动连接MCP服务器
AI智能选择合适的工具
无需用户干预

使用流程总结

复制代码

1. 创建/编辑 .mcp.json
   ↓
2. 重启 Claude Code
   ↓
3. 正常提问
   ↓
4. AI自动使用MCP工具
   ↓
5. 获得增强的回答