MCP使用指南

本指南将详细介绍如何设置和使用MCP (Model Context Protocol)，包括环境准备、安装配置、以及具体的使用方法。

导航

本章节内容分为以下部分：

• 基础设置与使用（本页）- 环境准备、基本安装和配置方法
• 平台使用指南 - 在不同平台上设置和使用MCP的详细教程

1. 环境准备

在开始使用MCP之前，需要确保您的系统满足以下基本要求：

1.1 系统需求

• 操作系统：

  • macOS
  • Windows
  • Linux (部分功能可能受限)

• 硬件要求：

  • 至少4GB内存
  • 至少10GB可用磁盘空间

1.2 必要的软件环境

以下是使用MCP必须安装的软件：

1. Node.js：v18或更高版本

   # 检查Node.js版本
   node --version
    
   # 如果未安装，从https://nodejs.org/下载并安装

2. Python：v3.8或更高版本

   # 检查Python版本
   python --version
    
   # 如果未安装，从https://python.org/下载并安装

3. UV包管理器：Python包管理工具，用于安装MCP服务器

   # 安装UV
   pip install uv
    
   # 验证安装
   uv --version

1.3 其他可选软件

根据您打算使用的MCP服务器类型，可能需要安装其他软件：

• Git：用于克隆和管理代码仓库
• Docker：用于运行容器化的MCP服务器
• 数据库软件：如SQLite、PostgreSQL等，视使用的服务器类型而定

2. 支持平台

• AI 对话工具

  • Claude桌面应用

• AI 编辑器

  • Cursor
  • VSCode (通过Cline)
  • Windsurf

• Agent 框架

  • 微软 AutoGen
  • HuggingFace 的 Smolagents

• 平台使用指南 - 在不同平台上设置和使用MCP的详细教程

3. 安装您的第一个MCP服务器

涉及的token用.env文件保存

我们将使用Cursor IDE作为示例，演示如何安装和配置MCP服务器。Cursor IDE内置了MCP支持，是开发者使用MCP的理想选择。

3.1 在Cursor中配置MCP服务器

1. 打开Cursor IDE
2. 打开设置面板（可通过快捷键Ctrl+,或Cmd+,）
3. 在左侧导航栏找到MCP服务器配置
4. 点击"常见新MCP服务"按钮，打开MCP配置文件

3.2 安装文件系统MCP服务器

文件系统MCP服务器是最常用的服务器之一，允许AI助手访问和操作您本地文件系统中的文件。

1. 在MCP配置JSON中添加以下内容：

   {
     "mcpServers": {
       "filesystem": {
         "command": "npx",
         "args": ["-y", "@modelcontextprotocol/server-filesystem", "工作目录绝对路径，如G:\\demo"]
       }
     }
   }

2. 保存配置文件，重启该mcp服务

3. 验证安装：

   • 在Cursor的聊天面板中询问Claude：请列出当前项目中的文件
   • 如果配置正确，Claude将能够列出您指定目录中的文件

3.3 安装Brave搜索MCP服务器

Brave搜索MCP服务器允许Claude进行网络搜索，获取最新信息。

1. 首先，您需要获取Brave API密钥：

   • 访问Brave API
   • 注册并选择免费套餐（每月最多2,000次查询）

   需要绑定境外信用卡

   • 生成并复制您的API密钥

2. 在MCP配置JSON中添加以下内容：

   {
     "mcpServers": {
       "filesystem": {
         "command": "npx",
         "args": ["-y", "@modelcontextprotocol/server-filesystem"],
         "env": {
           "BRAVE_API_KEY": "您的Brave API密钥"
         }
       }
     }
   }

3. 保存配置文件，重启该mcp服务

4. 验证安装：

   • 在Cursor的聊天面板中询问：使用Brave搜索引擎查找关于"最新AI发展"的信息
   • 如果配置正确，Claude将能够执行搜索并返回结果

3.4 安装GitHub MCP服务器

GitHub MCP服务器允许Claude直接与GitHub仓库交互，执行文件操作、仓库管理、搜索功能等。

1. 首先，您需要创建GitHub个人访问令牌（Personal Access Token）：

   • 访问GitHub设置 > 开发者设置 > 个人访问令牌
   • 选择"Generate new token"（生成新令牌）
   • 为您的令牌选择适当的权限范围：
     • 如果需要完全控制私有仓库，选择repo权限
     • 如果只需操作公共仓库，选择public_repo权限
   • 生成并复制您的令牌（注意：令牌只会显示一次）

2. 在MCP配置JSON中添加以下内容：

   {
     "mcpServers": {
       "github": {
         "command": "cmd",
         "args": [
           "/c",
           "npx",
           "-y",
           "@modelcontextprotocol/server-github"
         ],
         "env": {
           "GITHUB_PERSONAL_ACCESS_TOKEN": "您的GitHub个人访问令牌"
         }
       }
     }
   }

3. 保存配置文件，重启该mcp服务

4. 验证安装：

   • 在Cursor的聊天面板中询问：使用GitHub API搜索关于"MCP"的仓库
   • 如果配置正确，Claude将能够执行搜索并返回结果

5. GitHub MCP服务器功能：

   • 文件操作：创建或更新文件、获取文件内容
   • 仓库管理：创建仓库、搜索仓库
   • Issue管理：创建Issue、评论Issue
   • PR操作：创建PR、查看PR、合并PR
   • 高级搜索：搜索代码、Issue/PR、用户

6. 常用搜索语法示例：

   • 代码搜索：q: "import express" language:typescript path:src/
   • Issue搜索：q: "memory leak" is:issue is:open label:bug
   • 用户搜索：q: "fullstack developer" location:London followers:>100

4. 使用MCP服务器

一旦配置好MCP服务器，您就可以开始通过Cursor IDE与它们交互。

4.1 使用文件系统服务器

以下是在Cursor IDE的聊天面板中使用文件系统服务器的示例：

列出目录内容：

请列出当前项目目录中的所有文件

读取文件内容：

请阅读并总结src/App.js文件的内容

创建新文件：

请在项目根目录下创建一个新的README.md文件，内容包括项目标题、简介和安装说明

修改现有文件：

请在package.json文件中添加lodash依赖，版本为最新版

4.2 使用Brave搜索服务器

以下是在Cursor IDE中使用Brave搜索服务器的示例：

进行基本搜索：

使用Brave搜索引擎查找有关"React最佳实践"的信息

获取特定信息：

请搜索并告诉我最新的Node.js LTS版本号及其发布日期

结合代码和搜索：

请根据我的package.json文件搜索可能存在的依赖冲突，并提出解决方案

4.3 在开发过程中使用MCP

Cursor的强大之处在于它将编码与MCP无缝集成，以下是一些开发场景：

代码分析：

请分析当前项目中的组件结构，并绘制组件关系图

调试辅助：

请找出src目录下所有包含console.log的语句，并帮我评估是否应当保留

重构代码：

请分析src/utils/helpers.js文件并提出重构建议，使其更符合现代JavaScript最佳实践

5. 高级MCP使用技巧

5.1 同时使用多个MCP服务器

在Cursor中，MCP的一个强大功能是能够同时连接多个服务器，让AI助手协同使用不同的工具处理复杂的开发任务：

请分析当前项目的性能问题，搜索相关的优化方案，然后生成一个优化计划文档保存到docs目录

上述请求会同时使用文件系统服务器、代码分析和Brave搜索服务器，无缝集成多种功能。

5.2 使用环境变量保护敏感信息

在Cursor的MCP配置中，当需要API密钥时，建议使用环境变量来保护敏感信息：

{
  "mcpServers": {
    "github": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-github"],
      "env": {
        "GITHUB_TOKEN": "${GITHUB_TOKEN}"
      }
    }
  }
}

这样配置后，Cursor会从系统环境变量中读取GITHUB_TOKEN，而不是将其硬编码在配置文件中。

5.3 限制MCP服务器访问权限

为了安全起见，建议在Cursor的MCP配置中限制文件系统服务器只能访问当前项目目录：

{
  "mcpServers": {
    "filesystem": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-filesystem"],
      "resources": {
        "paths": ["${workspaceFolder}"],
        "readOnly": false
      }
    }
  }
}

这样配置后，Claude只能访问当前打开的项目目录，提高了安全性。

6. 构建自定义MCP服务器

如果现有的MCP服务器不能满足您的需求，您可以构建自己的自定义服务器。

6.1 准备工作

1. 确保已安装必要的开发工具：

   • Node.js和npm
   • Python和uv
   • Git

2. 选择适合的编程语言：

   • TypeScript/JavaScript
   • Python
   • 其他支持的语言

6.2 使用Python创建MCP服务器

下面将创建实用示例作为演示：一个笔记管理MCP服务器，它可以添加、删除和查看Markdown格式的笔记

创建项目

1. 创建新项目目录：

   mkdir my_mcp_server
   cd my_mcp_server

2. 安装MCP服务器创建工具：

   pip install uv create-mcp-server

3. 使用MCP提供的工程创建器创建模板项目：

通过agent创建

create-mcp-server 创建自定义的 mcpserver
然后会生成一个文件夹，里头的 README 给出了 mcp 的配置，可以复制到 mcp.json 中

根据README提供的配置复制到mcp.json

create-mcp-server my_service
cd my_service

修改服务器代码

通过agent创建，提出需求（以下为例子）

帮我把 @server.py 改成一个可以添加、删除、查看所有笔记列表的 mcpserver， 笔记会存放在 这个服务器的文件夹下，保存为 markdown

运行服务器

python -m my_service

根据README提供mcp配置启动服务，可开始agent使用：

1. 创建新笔记：

   请创建一个标题为"项目计划"的笔记，内容应包括项目目标、时间线和责任人

2. 列出所有笔记：

   请列出我所有的笔记

3. 查看特定笔记：

   请显示ID为"1234_项目计划"的笔记内容

4. 更新笔记：

   请更新ID为"1234_项目计划"的笔记，添加一个新的部分"风险管理"

5. 删除笔记：

   请删除ID为"1234_项目计划"的笔记

这个笔记管理MCP服务器使您的AI助手能够直接管理你的Markdown笔记，这对于项目管理、日常笔记和学习资料整理非常有用。

6.3 高德地图MCP使用示例

根据README提供mcp配置启动服务，可开始agent使用：

1. 搜索兴趣点：

   请搜索北京的故宫博物院

2. 地理编码：

   请将地址"北京市海淀区中关村"转换为经纬度坐标

3. 逆地理编码：

   请查询经纬度"116.481499,39.990475"对应的地址信息

4. 路线规划：

   请规划从北京故宫到颐和园的驾车路线

5. 天气查询：

   请查询北京市今天和未来几天的天气情况

6. 智能旅游路线：

   请帮我规划北京三日游，包含故宫、长城、颐和园、天坛和鸟巢

高德地图MCP服务使您的AI助手能够进行地理位置查询、路线规划和天气查询等功能，这对于旅行规划、出行导航和位置服务非常有用。

6.4 使用TypeScript创建MCP服务器

创建项目

1. 初始化项目：

   mkdir my-ts-mcp-server
   cd my-ts-mcp-server
   npm init -y

2. 安装依赖：

   npm install @modelcontextprotocol/sdk typescript ts-node

3. 创建TypeScript配置：

   npx tsc --init

4. 创建README.md：

@gaode 是一个MCP服务项目，创建README.md，且给出了 mcp 的配置，可以复制到 mcp.json 中

根据README提供的配置复制到mcp.json，记得修改密钥

编写服务器代码

创建src/index.ts文件：

创建@index.ts ，即提供调用高德的api的mcp服务，而可以通过调用这个mcp服务实现规划旅游路线更加可视化与合理

运行服务器

npm start

7. 常见问题与故障排除

7.1 MCP服务器不显示在Cursor中

问题：配置了MCP服务器，但Claude无法访问服务器功能。

解决方案：

1. 检查Cursor设置中MCP配置是否正确
2. 验证配置的命令是否可在终端/命令提示符中执行
3. 重新加载Cursor窗口（通过命令面板选择"Reload Window"）
4. 确认Node.js和npm已正确安装，版本不低于要求

7.2 安装依赖失败

问题：在Cursor中安装MCP服务器时依赖安装失败。

解决方案：

1. 在终端中手动运行相关命令检查错误信息：

   npm install -g @modelcontextprotocol/server-filesystem

2. 确保网络连接正常，可能需要配置代理
3. 确保Cursor有足够的权限安装全局包
4. 更新npm：

   npm install -g npm

7.3 文件系统访问问题

问题：在Cursor中，Claude无法访问或修改项目文件。

解决方案：

1. 检查MCP配置中的路径设置，确保包含了当前工作目录
2. 确认目录和文件的权限
3. 检查文件是否已在其他程序中打开且被锁定
4. 在Windows上，检查防病毒软件是否阻止了访问

7.4 Cursor中的MCP工具提示不完整

问题：Cursor中Claude没有显示所有可用的MCP工具。

解决方案：

1. 检查MCP服务器是否正常运行
2. 尝试重新发起对话
3. 检查Claude API限制
4. 更新Cursor到最新版本

8. MCP使用最佳实践

8.1 Cursor中的MCP安全性最佳实践

1. 最小权限原则：使用${workspaceFolder}变量限制文件系统服务器只访问当前项目
2. 使用环境变量：通过Cursor支持的环境变量语法${ENV_VAR}