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服务器的类型类型1npm包通过npx启动配置示例{context7:{type:stdio,command:npx,args:[-y,upstash/context7-mcplatest]}}下载位置~/.npm/_npx/ # npx缓存目录 或 /tmp/npx-xxxxx/ # 临时目录特点✅ 自动下载和管理✅ 使用latest总是获取最新版本✅ 不需要手动安装⚠️ 首次启动会下载需要网络查看下载的包# 查看npx缓存ls~/.npm/_npx/# 手动安装到全局可选npminstall-gupstash/context7-mcp类型2本地项目Python/Node.js配置示例{serena:{type:stdio,command:python,args:[/home/cbx/code/serena/mcp_server.py]}}位置/home/cbx/code/serena/ # 你指定的本地路径特点✅ 完全控制代码✅ 可以自定义功能⚠️ 需要手动维护类型3全局命令配置示例{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 HooksClaude的内部流程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会自动使用吗答案✅是的完全自动自动使用的条件条件1MCP服务器已启动Claude Code启动时自动启动所有配置的MCP服务器条件2AI判断需要使用工具基于用户问题AI自动决定是否调用MCP工具条件3工具可用MCP服务器正常运行连接正常自动使用的流程需要文档需要搜索需要浏览器不需要工具用户提问AI分析问题调用context7调用open-websearch调用Playwright直接回答返回结果用户无需做什么❌不需要输入特殊命令如/search、/docs手动启动MCP服务器指定使用哪个工具✅只需要正常提问AI自动判断和使用工具 五、完整配置示例示例1最小配置使用npm包文件位置~/.config/claude-code/mcp.json{mcpServers:{context7:{type:stdio,command:npx,args:[-y,upstash/context7-mcplatest],env:{}}}}使用保存配置文件重启Claude Code直接提问“如何使用Vue 3”AI自动调用context7查询文档示例2多工具配置文件位置/your-project/.mcp.json{mcpServers:{context7:{type:stdio,command:npx,args:[-y,upstash/context7-mcplatest],env:{}},open-websearch:{type:stdio,command:npx,args:[-y,open-websearchlatest],env:{DEFAULT_SEARCH_ENGINE:duckduckgo}},playwright:{type:stdio,command:npx,args:[-y,playwright/mcplatest],env:{}}}}使用在项目根目录创建.mcp.json重启Claude Code提问时AI会自动选择合适的工具示例3自定义工具配置文件位置~/.config/claude-code/mcp.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自动调用自定义数据库工具 六、常见问题排查问题1MCP工具没有自动使用可能原因❌ MCP服务器启动失败❌ 配置文件路径错误❌ AI判断不需要使用工具排查步骤# 1. 检查配置文件是否存在ls~/.config/claude-code/mcp.jsonls.mcp.json# 2. 验证JSON格式cat~/.config/claude-code/mcp.json|jq.# 3. 手动测试MCP服务器npx-yupstash/context7-mcplatest# 4. 查看Claude Code日志# 启动时会显示MCP连接状态解决方法确保配置文件格式正确重启Claude Code检查网络连接npm包需要下载问题2首次启动很慢原因npx需要下载npm包网络速度影响解决方法# 方法1预先安装到全局npminstall-gupstash/context7-mcpnpminstall-gopen-websearchnpminstall-gplaywright/mcp# 方法2使用国内镜像npmconfigsetregistry https://registry.npmmirror.com# 方法3等待首次下载完成只需一次问题3MCP工具调用失败可能原因❌ 环境变量缺失如API_KEY❌ 权限问题❌ 依赖缺失排查步骤# 1. 检查环境变量echo$API_KEY# 2. 检查Python/Node.js版本python--versionnode--version# 3. 检查依赖pip list|grepmcpnpmlist-g|grepmcp解决方法在.mcp.json的env中设置环境变量安装必要的依赖检查文件权限 七、MCP工具使用对比手动命令 vs 自动使用特性手动命令MCP自动使用触发方式输入/commandAI自动判断用户体验需要记住命令自然对话灵活性固定命令智能选择学习成本需要学习命令零学习成本适用场景明确操作所有场景示例对比手动命令方式假设用户/search React Hooks AI搜索中... AI返回结果MCP自动方式实际用户React Hooks怎么用 AI自动调用context7让我查询最新文档... AIReact Hooks是...返回详细说明结论MCP自动使用更自然、更智能 八、最佳实践1. 配置文件管理推荐结构~/.config/claude-code/ ├── mcp.json # 全局通用工具 └── projects/ └── dmv/ └── .mcp.json # 项目专用工具全局配置通用工具{mcpServers:{context7:{...},open-websearch:{...},playwright:{...}}}项目配置专用工具{mcpServers:{project-database:{...},project-api:{...}}}2. 环境变量管理不要硬编码敏感信息❌错误做法{env:{API_KEY:sk-1234567890abcdef}}✅正确做法{env:{API_KEY:${API_KEY}}}在系统中设置环境变量# Linux/MacexportAPI_KEYsk-1234567890abcdef# WindowssetAPI_KEYsk-1234567890abcdef3. 版本管理使用固定版本生产环境{args:[-y,upstash/context7-mcp1.2.3]}使用最新版本开发环境{args:[-y,upstash/context7-mcplatest]}4. 性能优化减少启动时间# 预先安装常用工具npminstall-gupstash/context7-mcpnpminstall-gopen-websearchnpminstall-gplaywright/mcp配置使用全局安装{command:context7-mcp,args:[]} 九、总结核心要点Q1: 只需要在.mcp.json中定义就可以了吗A: ✅ 是的但有两个位置全局~/.config/claude-code/mcp.json项目/project/.mcp.jsonQ2: 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. 获得增强的回答
