03-MCP实战指南

03-MCP实战指南MCP (Model Context Protocol) 是 Cursor 扩展 AI 能力的关键让 AI 能够访问文件系统、搜索网络、控制浏览器等。一、MCP 基础概念1.1 什么是 MCPMCP (Model Context Protocol) 是一种开放协议让 AI 助手能够安全地访问外部工具和数据源。类比理解:MCP 就像 AI 的插件系统 - File System MCP 让 AI 能读写文件 - Web Search MCP 让 AI 能搜索网络 - Browser MCP 让 AI 能操作浏览器 - GitHub MCP 让 AI 能提交代码、创建 PR1.2 Cursor 中的 MCPCursor 内置了多个 MCP 服务器可以在Settings MCP中配置。二、常用 MCP 服务器详解2.1 File System MCP功能: 让 AI 安全地访问本地文件系统适用场景:读取项目配置文件批量处理数据文件自动生成文档配置方法:// Cursor Settings MCP File System{mcpServers:{filesystem:{command:npx,args:[-y,modelcontextprotocol/server-filesystem,/path/to/allowed/dir]}}}使用示例:用户读取项目根目录下的 requirements.txt分析依赖版本 AI通过 File System MCP 读取文件返回分析结果2.2 Web Search MCP功能: 让 AI 搜索网络获取最新信息适用场景:查询最新技术文档搜索 API 使用方法查找最佳实践配置方法:// 通常内置无需额外配置{mcpServers:{web-search:{command:npx,args:[-y,modelcontextprotocol/server-web-search]}}}使用示例:用户搜索 pandas 2.0 的新特性 AI通过 Web Search MCP 搜索返回结构化结果2.3 Browser MCP功能: 让 AI 控制浏览器进行自动化操作适用场景:测试 Web 应用抓取网页数据验证 API 响应配置方法:{mcpServers:{browser:{command:npx,args:[-y,modelcontextprotocol/server-browser]}}}使用示例:用户帮我测试 http://localhost:8000/docs 页面是否正常 AI通过 Browser MCP 访问页面返回状态码和内容摘要2.4 Context7 MCP功能: 文档查询和索引适用场景:查询 Python/pandas 文档查找 API 详细说明代码补全上下文配置方法:{mcpServers:{context7:{command:npx,args:[-y,upstash/context7-mcp]}}}2.5 GitHub MCP功能: 远程操作 GitHub 仓库实现代码提交、PR 创建、Issue 管理等适用场景:自动提交代码到 GitHub 仓库创建 Pull Request 进行代码审查管理 Issues 和 Projects读取仓库文件和代码自动发布 Release配置方法:方式1使用 GitHub Token推荐生成 GitHub Personal Access Token:访问 https://github.com/settings/tokens点击 “Generate new token (classic)”勾选权限repo完整仓库访问、workflow、gist复制生成的 Token在 Cursor 中配置{mcpServers:{github:{command:npx,args:[-y,modelcontextprotocol/server-github],env:{GITHUB_PERSONAL_ACCESS_TOKEN:ghp_your_token_here}}}}方式2使用环境变量更安全# Windows PowerShell$env:GITHUB_PERSONAL_ACCESS_TOKENghp_your_token_here# macOS/LinuxexportGITHUB_PERSONAL_ACCESS_TOKENghp_your_token_here然后在 Cursor MCP 配置中不填写 token服务器会自动读取环境变量。使用示例:示例1提交代码用户将当前修改提交到 GitHub提交信息修复用户认证bug Cursor 执行流程 1. 通过 GitHub MCP 获取当前仓库状态 2. 创建 commit 并推送 3. 返回提交结果和链接示例2创建 Pull Request用户创建一个 PR标题添加用户登录功能描述实现了JWT认证包含登录和注册API Cursor 执行流程 1. 推送当前分支到远程 2. 基于 main 分支创建 PR 3. 添加指定标题和描述 4. 返回 PR 链接和编号示例3读取仓库代码用户查看 github.com/myorg/backend 仓库的 src/auth.py 文件内容 AI通过 GitHub MCP 远程读取文件返回代码内容Python 项目实战自动发布流程用户帮我完成以下发布流程 1. 更新版本号到 1.2.0 2. 提交到 GitHub 3. 创建 Release标题v1.2.0 新增数据分析模块 4. 生成 Release Notes Cursor 执行 1. 修改 setup.py 或 pyproject.toml 中的版本号 2. 通过 GitHub MCP 提交代码 3. 创建 Tag v1.2.0 4. 创建 Release 并自动生成变更日志三、MCP 配置实战3.1 配置位置Cursor 2.6.22推荐方式 - 直接搜索1. 按 Ctrl, 打开 Settings 2. 在顶部搜索框输入 MCP 3. 找到 MCP: Enabled 或 MCP Servers 相关设置菜单方式Cursor → Settings → Features → MCP 或 Cursor → Settings → Cursor Settings → Features → MCP快捷方式部分版本支持CtrlShiftP→ 输入 “MCP” → 选择相关命令3.2 添加 MCP 服务器步骤1: 打开 MCP 设置面板步骤2: 点击 “Add New MCP Server”步骤3: 填写配置{name:my-filesystem,transport:stdio,command:npx,args:[-y,modelcontextprotocol/server-filesystem,D:/my-project],env:{}}步骤4: 保存并测试3.3 Python 开发者推荐配置{mcpServers:{filesystem:{command:npx,args:[-y,modelcontextprotocol/server-filesystem,.]},context7:{command:npx,args:[-y,upstash/context7-mcp]},github:{command:npx,args:[-y,modelcontextprotocol/server-github],env:{GITHUB_PERSONAL_ACCESS_TOKEN:${GITHUB_TOKEN}}}}}提示: 将${GITHUB_TOKEN}替换为你的实际 GitHub Personal Access Token或使用环境变量方式配置。四、MCP 使用场景实战场景1数据分析项目需求: 读取 CSV 文件并生成分析报告用户分析 data/sales.csv 文件的数据分布生成可视化代码 Cursor 执行流程 1. 通过 File System MCP 读取 CSV 文件 2. 分析数据结构 3. 生成 pandas 分析代码 4. 生成 matplotlib 可视化代码生成的代码示例:importpandasaspdimportmatplotlib.pyplotasplt# 读取数据File System MCP 提供文件路径dfpd.read_csv(data/sales.csv)# 基础分析print(f数据形状:{df.shape})print(f\n列信息:\n{df.dtypes})print(f\n统计摘要:\n{df.describe()})# 可视化plt.figure(figsize(10,6))df[sales].hist(bins20)plt.title(Sales Distribution)plt.savefig(output/sales_dist.png)场景2查询技术文档需求: 查询 FastAPI 最新版本的使用方法用户FastAPI 最新版本如何配置 CORS Cursor 执行流程 1. 通过 Web Search MCP 搜索 FastAPI CORS 最新版本 2. 提取官方文档内容 3. 返回代码示例返回结果:fromfastapiimportFastAPIfromfastapi.middleware.corsimportCORSMiddleware appFastAPI()app.add_middleware(CORSMiddleware,allow_origins[*],allow_credentialsTrue,allow_methods[*],allow_headers[*],)场景3API 测试需求: 测试本地开发的 API用户测试 http://localhost:8000/api/users 接口 Cursor 执行流程 1. 通过 Browser MCP 访问该 URL 2. 返回响应状态码和内容 3. 分析响应结构场景4自动提交代码到 GitHub需求: 完成开发后自动提交代码并创建 PR用户我已经完成了用户认证模块的开发帮我 1. 提交所有修改到 GitHub 2. 创建一个新的分支 feature/auth 3. 创建一个 Pull Request 合并到 main 分支 4. PR 标题写上实现用户认证功能 Cursor 执行流程 1. 通过 File System MCP 检查本地修改的文件 2. 通过 GitHub MCP 创建分支 feature/auth 3. 提交代码到新分支 4. 创建 Pull Request设置标题和描述 5. 返回 PR 链接供用户查看生成的 PR 信息:标题: 实现用户认证功能 描述: ## 变更内容 - 实现 JWT 认证机制 - 添加用户登录/注册 API - 添加密码加密存储 - 添加认证中间件 ## 测试情况 - [x] 单元测试通过 - [x] 手动测试通过 ## 相关 Issue Closes #123五、自定义 MCP 服务器5.1 何时需要自定义需要访问公司内部 API需要集成特定工具需要自定义数据处理逻辑5.2 简单 MCP 服务器示例# my_mcp_server.pyfrommcp.serverimportServerfrommcp.typesimportTextContent appServer(my-python-server)app.call_tool()asyncdefanalyze_python_code(code:str)-list:分析 Python 代码复杂度linescode.split(\n)complexitylen([lforlinlinesifforinlorwhileinl])return[TextContent(typetext,textf代码行数:{len(lines)}, 复杂度指标:{complexity})]if__name____main__:app.run()5.3 配置自定义服务器{mcpServers:{my-analyzer:{command:python,args:[/path/to/my_mcp_server.py]}}}六、常见问题Q1: MCP 服务器启动失败检查项:Node.js 版本是否 18命令路径是否正确防火墙是否阻挡解决方法:# 检查 Node 版本node--version# 手动测试 MCP 服务器npx-ymodelcontextprotocol/server-filesystem.Q2: AI 无法调用 MCP 工具检查项:MCP 服务器状态是否为 “Running”提示词是否明确需要使用工具权限设置是否正确Q3: File System MCP 访问被拒绝原因: 安全限制只能访问配置时指定的目录解决: 在配置时指定正确的允许目录路径Q4: GitHub MCP 认证失败错误信息:401 Bad credentials 或 403 Resource not accessible by personal access token检查项:Token 是否已过期Token 是否有repo权限是否将 Token 正确配置到环境变量或 MCP 配置中解决方法:# 1. 检查 GitHub Token 是否有效curl-HAuthorization: token ghp_your_token\https://api.github.com/user# 2. 如果无效重新生成 Token# 访问 https://github.com/settings/tokens# 3. 检查仓库权限# 确保 Token 有权限访问目标仓库# 如果是私有仓库需要 repo 权限# 如果是组织仓库可能需要额外授权Token 权限要求:✅repo- 访问私有仓库✅public_repo- 访问公开仓库✅workflow- 管理 GitHub Actions✅gist- 访问 Gist七、最佳实践实践说明最小权限只给 MCP 必要的目录访问权限敏感信息不要在 MCP 配置中硬编码 API Key测试先行配置后先测试 MCP 是否正常工作组合使用多个 MCP 组合使用解决复杂问题GitHub 安全使用环境变量存储 Token定期更换不要提交到仓库代码审查使用 GitHub MCP 创建 PR 后仍需要人工审查再合并八、下一步学习完成本指南后建议学习04-Skills自定义开发.md - 创建自定义技能08-实战Python数据分析工具.md - MCP 实战项目